m365-cli

Agent-friendly Microsoft 365 CLI — read and manage Outlook email, calendar, and people lookups via the Microsoft Graph API. All commands emit structured JSON to stdout; errors emit JSON to stderr with a non-zero exit code, so the tool is usable both by humans and by scripts/agents.

Status: alpha (0.1.2). Surface area and JSON shapes may change.

Requirements

• Python 3.11+
• An Azure AD app registration in the tenant you want to access (Client ID + Tenant ID). A client secret is only required for the headless client_credentials mode.

Install

pip install m365-cli

After install you'll have an m365 command on your PATH.

Azure app registration (one-time)

1. Azure Portal → App registrations → New registration.
2. Supported account types: pick what matches your tenant (single-tenant for most users; "common" works for personal multi-tenant).
3. After creation, go to Authentication → Advanced settings and set Allow public client flows = Yes (required for the device-code flow).
4. Go to API permissions → Add a permission → Microsoft Graph → Delegated and add: User.Read, Mail.Read, Mail.ReadWrite, Mail.Send, Calendars.Read, Calendars.ReadWrite, People.Read. Grant admin consent if your tenant requires it.
5. Copy the Application (client) ID and Directory (tenant) ID — you'll paste them into the setup wizard.

For the headless client_credentials mode you'll also need a client secret and Application (not Delegated) Graph permissions, with admin consent.

Configure

Run the interactive wizard (writes a .env in the current directory):

m365 setup

Then authenticate:

m365 auth login        # device-code flow; opens a browser
m365 auth status       # confirm who you're signed in as

Configuration is read from the following locations (later overrides earlier):

1. ~/.m365/.env — global config written by m365 setup (works from any directory)
2. .env in the current working directory — per-project override

Environment variables set in the shell always override both files. See .env.example for all supported keys.

Common commands

# Email
m365 email list   --limit 10 --unread-only
m365 email list   --since 2025-01-01 --until 2025-01-31   # filter by date range
m365 email search --query "invoice"                        # full-text search (server-side)
m365 email search --query "budget" --folder "Archive"     # scope to a folder
m365 email read   <message-id>
m365 email send   --to alice@example.com --subject "hi" --body "hello"
m365 email reply  <message-id> --body "thanks"

# Calendar
m365 calendar events       --start 2025-04-25 --end 2025-04-30
m365 calendar create       --subject "Sync" --start ... --end ... --attendee ...
m365 calendar availability --user a@example.com --user b@example.com --start ... --end ...

# People
m365 people search --query "alice"

# Auth
m365 auth login | logout | status | token

m365 --help lists every group; each group and command has its own --help.

email search vs email list

Limitation: The Microsoft Graph API does not allow $search and $filter on the same messages request. When --query is supplied to email search, the --since, --until, and --unread-only flags are silently ignored. Use email list when you need date or read-state filtering without full-text search.

Where things live on disk

Security notes

• The refresh token is encrypted at rest with Fernet. The encryption key is stored in ~/.m365/.key next to the ciphertext with the same permissions, so the on-disk encryption is defense-in-depth, not a barrier against a local attacker who already has read access to your home directory. Treat ~/.m365/ as sensitive.
• To make tokens portable across machines, export the auto-generated key (printed on first login) into TOKEN_ENCRYPTION_KEY in your .env.
• m365 auth token prints the raw bearer access token to stdout — use it only when you intend to pipe it into another tool.
• client_credentials mode requires MICROSOFT_CLIENT_SECRET. Never commit it. .env, *.key, *.pem, and *.p12 are gitignored.
• Logs in ~/.m365/m365.log may contain Graph request metadata (URLs, status codes) but tokens are truncated before being logged.

Exit codes

Development

git clone git@github.com:goetzcj/m365-cli.git
cd m365-cli
uv sync --extra dev      # or: pip install -e ".[dev]"
pytest

License

MIT — see LICENSE.