Skip to content

account.md

Latest commit

 

History

History
256 lines (192 loc) · 9.89 KB

account.md

File metadata and controls

256 lines (192 loc) · 9.89 KB
Raw

Account Commands

Manage multiple Microsoft accounts. Each account has an alias (short name), a client ID, and optionally a tenant ID. You can switch between accounts using --account <alias> on any command.

Every account command accepts global options (--format, --json, --output, --verbose).

account add <alias>

Register a new account with an alias. This does not authenticate — it only stores the configuration. Run auth login --account <alias> afterwards to authenticate.

# Personal Microsoft account
outlook-cli account add personal --client-id YOUR_CLIENT_ID

# Work/school account with specific tenant
outlook-cli account add work --client-id YOUR_CLIENT_ID --tenant contoso.onmicrosoft.com

# Read-only account (cannot send, draft, move, delete, flag, or modify)
outlook-cli account add monitor --client-id YOUR_CLIENT_ID --read-only

# Custom scopes (advanced — fine-grained permission control)
outlook-cli account add agent --client-id YOUR_CLIENT_ID --scopes "User.Read,Mail.Read,Mail.Send,offline_access"

# Bridge account (COM Bridge — no Azure/Graph required)
outlook-cli account add bridge --client-id not-used --provider bridge --bridge-url http://localhost:8465 --bridge-secret SECRET

# Bridge with multi-account routing (targets a specific Outlook store)
outlook-cli account add shared --client-id not-used --provider bridge --bridge-url http://localhost:8465 --bridge-secret SECRET --bridge-account shared
Option Description Default
--client-id <id> Azure app registration client ID. One app registration can serve multiple accounts — each user authenticates independently. Required
--tenant <id> Azure AD / Entra ID tenant. Use common for personal accounts. For work/school, use the tenant domain or GUID. common
--read-only Create the account in read-only mode. At login, only read scopes are requested (Mail.Read, Calendars.Read, Contacts.Read). All write commands are blocked before they reach the Graph API. false
--scopes <list> Comma-separated list of custom MSAL scopes to request at login. Overrides the default scope set. For advanced use — most users should use --read-only instead. Full default scopes
--provider <type> Backend provider: graph (default) or bridge. Bridge routes through a COM Bridge server instead of Microsoft Graph API. graph
--bridge-url <url> COM Bridge server URL. Required when --provider bridge. —
--bridge-secret <secret> Shared HMAC-SHA256 secret for bridge authentication. —
--bridge-account <name> Bridge account name for multi-store routing. Maps to an account entry in the bridge server's bridge.json. Omit to use the default Outlook store. —

Arguments:

  • <alias> — A short name for the account (e.g., personal, work, monitor). Used with --account on all commands. Must be unique.

After adding: Run outlook-cli auth login --account <alias> to authenticate. The login will request only the scopes configured for that account.

Read-Only Accounts

Read-only accounts are enforced at two layers:

  1. MSAL scopes (security boundary): At login, only read-only scopes are requested. The resulting token cannot perform write operations — Microsoft Graph returns HTTP 403 if attempted.
  2. CLI write guard (UX): Before any write command (mail send, mail draft, mail reply, mail forward, mail move, mail flag, mail mark-read, mail delete, calendar create, calendar delete), the CLI checks the account mode and rejects immediately with a clear error.
outlook-cli account add monitor --client-id abc123 --read-only
outlook-cli auth login --account monitor        # Requests only read scopes
outlook-cli mail inbox --account monitor         # ✓ Works fine
outlook-cli mail send msg-id --account monitor   # ✗ Blocked immediately
# ✗ Account "monitor" is read-only. Cannot send draft.

One App Registration, Multiple Accounts

You can use the same Azure app registration (client ID) for multiple accounts. Each user authenticates with their own Microsoft credentials and gets separate tokens:

outlook-cli account add personal --client-id abc123
outlook-cli account add work --client-id abc123 --tenant contoso.onmicrosoft.com
outlook-cli auth login --account personal    # Signs in as john@outlook.com
outlook-cli auth login --account work        # Signs in as john@contoso.com

For stronger isolation, use different app registrations (different --client-id values). Each app registration can be configured in Azure Portal with different API permissions.

account remove <alias>

Remove an account and delete its cached tokens. This deletes the encrypted cache file (~/.outlook-cli/cache-{alias}.enc).

outlook-cli account remove work

Arguments:

  • <alias> — The account alias to remove. Must match an existing account.

The account is removed from ~/.outlook-cli/accounts.json and its token cache is deleted. If this was the default account, no default is set — you'll need to set a new one with account set-default.

account rename <old-alias> <new-alias>

Rename an account alias without losing any configuration or cached tokens.

# Rename "bridge" to "work"
outlook-cli account rename bridge work

# Now use the new name
outlook-cli mail inbox --account work

Arguments:

  • <old-alias> — The current account alias.
  • <new-alias> — The new alias. Must not already exist.

If the renamed account was the default, the new alias becomes the new default automatically.

account list

List all configured accounts with their email addresses, default status, and mode.

outlook-cli account list
outlook-cli account list --json

Example output (text):

Accounts:
  default (default) — ac-jstall-ms@outlook.com [common]
  work — http://localhost:8465 [bridge: ✓ healthy]
  shared — http://localhost:8465 → shared-mailbox [bridge: ✓ healthy]

Bridge accounts show the bridge URL and a live health status (✓ healthy or offline) instead of an email address and tenant. If the account has a bridgeAccount mapping, it's shown with →.

Example output (JSON):

{
  "accounts": [
    {
      "alias": "personal",
      "email": "john@outlook.com",
      "clientId": "abc123...",
      "tenantId": "common",
      "mode": "full"
    },
    {
      "alias": "monitor",
      "email": "monitor@outlook.com",
      "clientId": "abc123...",
      "tenantId": "common",
      "mode": "read-only"
    }
  ],
  "defaultAccount": "personal"
}

account set <alias>

Modify settings on an existing account. Changes to mode, scopes, client ID, or tenant require re-authentication (auth login) to take effect.

# Make an existing account read-only
outlook-cli account set work --read-only

# Restore full access
outlook-cli account set work --mode full

# Set custom scopes
outlook-cli account set agent --scopes "Mail.Read,Mail.Send,offline_access"

# Change client ID (different app registration)
outlook-cli account set work --client-id NEW_CLIENT_ID
Option Description
--read-only Switch to read-only mode (shorthand for --mode read-only)
--mode <mode> Set mode: full (all operations) or read-only (read operations only)
--scopes <list> Comma-separated custom MSAL scopes
--client-id <id> Change the Azure app client ID
--tenant <id> Change the Azure AD tenant ID
--provider <type> Backend provider: graph or bridge
--bridge-url <url> COM Bridge server URL
--bridge-secret <secret> Shared HMAC-SHA256 secret for bridge authentication
--bridge-account <name> Bridge account name for multi-store routing

After changing: Run outlook-cli auth login --account <alias> to re-authenticate with the new settings. The old token continues to work until it expires, but it was issued with the previous scopes.

account set-default <alias>

Set which account is used by default when --account is not specified.

outlook-cli account set-default work

Arguments:

  • <alias> — The account alias to make default. Must match an existing account.

After this, all commands without --account will use the work account:

outlook-cli mail inbox            # Uses 'work' account
outlook-cli mail inbox --account personal  # Overrides to 'personal'

Account Configuration File

Account configuration is stored in ~/.outlook-cli/accounts.json. You can edit this file directly for advanced configuration (permissions, parent chains, send_to whitelists), but for basic account management, use the CLI commands.

{
  "accounts": {
    "personal": {
      "alias": "personal",
      "clientId": "abc123...",
      "tenantId": "common",
      "email": "john@outlook.com",
      "mode": "full"
    },
    "monitor": {
      "alias": "monitor",
      "clientId": "abc123...",
      "tenantId": "common",
      "email": "monitor@outlook.com",
      "mode": "read-only"
    },
    "agent": {
      "alias": "agent",
      "clientId": "def456...",
      "tenantId": "contoso.onmicrosoft.com",
      "email": "agent@contoso.com",
      "mode": "full",
      "scopes": ["User.Read", "Mail.Read", "Mail.Send", "offline_access"]
    }
  },
  "defaultAccount": "personal"
}

Fields:

Field Required Description
alias Yes Account alias (matches the key in the accounts object)
clientId Yes Azure app registration client ID
tenantId Yes Azure AD tenant (common for personal)
email No Set automatically after auth login
mode No full (default) or read-only
scopes No Custom MSAL scope list (overrides defaults at login)

For advanced features like permission restrictions, parent chains, and send_to whitelists, see MULTI-ACCOUNT.md and SECURITY.md.