Set up the Graph CLI
This guide takes a checkout to its first read-only Graph request. Use a designated mailbox that your application can access.
Prerequisites
You need Bun 1.3 or later, an Entra application and credential, tenant administrator consent, and an Exchange Online mailbox. Prepare Microsoft Graph access. The CLI calls Graph independently of a MailGen login.
Install dependencies
From the motherrepo root:
cd Architecture/GraphSyncExperimenter/cli-graph
bun install
If already in that directory, run only bun install.
Configure the application
| Variable | CLI use | Format |
|---|---|---|
TENANT_ID | Required | Entra tenant ID |
CLIENT_ID | Required | Application client ID |
CLIENT_SECRET | Required | Confidential application secret |
DELTA_LINK_ENCRYPTION_KEY | Not read | Used by separate sync/lab services, not this CLI |
Supply these runtime values through the ignored local .env or the process environment:
TENANT_ID=your-tenant-id
CLIENT_ID=your-application-client-id
CLIENT_SECRET=your-client-secret
Keep real credentials out of documentation, workflows, tests, and commits. .env.example contains configuration names, not a usable secret.
Grant application permissions
The tool uses Graph application permissions with administrator consent:
| Permission | Use |
|---|---|
Mail.ReadWrite | Read and modify messages/folders |
Mail.Send | Send as the selected mailbox |
MailboxSettings.ReadWrite | Manage Outlook master categories |
Directory user lookup can also require directory read access. Exchange application restrictions can limit mailbox reach after consent. Use that restriction for designated test mailboxes where appropriate.
Select a mailbox
--user-id <Graph-user-object-ID-or-UPN> identifies the target mailbox. A UPN such as person@example.com is readable, but the actual authorized target matters. For sending, that mailbox is the sender. There is no separate --from override.
Where the documentation displays a user selector, entering an ID/address updates examples only. Its browser key is t42.graphCli.userId. The legacy initial sample is tatar.bela@t42.hu. The value stays in browser storage and does not authenticate or execute a command. Reset clears the choice and restores the sample. Check copied commands before use.
Check installation
These local checks do not request mailbox data:
bun run typecheck
bun test
bun run cli -- --help
A passing test run and help output check local installation. Do not rely on a fixed test count.
Then make a read-only provider request:
bun run cli -- folder list --user-id person@example.com
Expect one JSON result with status: "Listed" and exit code 0. This checks the credential and mailbox scope without changing mail. label list and email list --folder-id inbox are other read-only first checks.
If the request returns 401, inspect application identity and credential expiry. For 403, inspect administrator consent and Exchange scope. See troubleshooting before attempting a write. Continue with the command reference.