mogcli

March 5, 2026 ยท View on GitHub

Unofficial agent-friendly Microsoft 365 CLI

mogcli is a Microsoft Graph CLI for personal Microsoft accounts (MSA) and enterprise Microsoft Entra ID accounts. It provides scriptable commands for Mail, Calendar, Contacts, Groups, Tasks, and OneDrive.

What mogcli supports

  • Multiple profiles with exactly one active profile at a time.
  • Consumer and enterprise audiences.
  • Delegated user auth and enterprise app-only auth.
  • Stable scripting output modes: --json and --plain.
  • Interactive delegated wizard (mog auth), advanced app-only wizard (mog auth app), settings editor (mog auth update), and non-interactive login (mog auth login).
  • Per-command scope requests in delegated mode (progressive consent).
  • --dry-run previews for write operations in Mail, Calendar, and OneDrive.

Workload support matrix

WorkloadDelegatedApp-only
MailYesYes (enterprise, requires target user)
CalendarYesNo
ContactsYesYes (enterprise, requires target user)
GroupsEnterprise onlyEnterprise only
Tasks (Microsoft To Do)YesNo
OneDriveYesYes (enterprise, requires target user)

Notes:

  • App-only mode is enterprise-only.
  • Calendar and tasks are intentionally blocked in app-only mode.
  • Groups are intentionally blocked for consumer profiles.

Install

Option 1: Build from source

git clone https://github.com/jaredpalmer/mogcli.git
cd mogcli
go build -o bin/mog ./cmd/mog
./bin/mog --help

Option 2: go install

go install github.com/jaredpalmer/mogcli/cmd/mog@latest
mog --help

Option 3: Homebrew

brew tap jaredpalmer/tap
brew install jaredpalmer/tap/mogcli
mog --help

Microsoft app setup prerequisites

Before login, create app registrations in Microsoft Entra:

  1. Consumer app registration (for MSA audience).
  2. Enterprise app registration (for work/school audience).

For delegated login:

  1. Enable public client flow in app Authentication settings.
  2. Add delegated Graph permissions for the workloads you plan to use.

For app-only login:

  1. Use an enterprise app registration.
  2. Add required application permissions.
  3. Grant admin consent.
  4. Create a client secret.

Quick start

mog auth

This wizard configures the profile and starts delegated device-code login.

Advanced app-only interactive setup (enterprise only):

mog auth app

2) Scripted delegated login

Consumer profile:

mog auth login \
  --profile personal \
  --audience consumer \
  --client-id <consumer-client-id> \
  --scope-workloads mail,calendar,contacts,tasks,onedrive

Enterprise delegated profile:

mog auth login \
  --profile work \
  --audience enterprise \
  --client-id <enterprise-client-id> \
  --tenant <tenant-id-or-domain> \
  --scope-workloads mail,calendar,contacts,tasks,onedrive,groups

3) Scripted app-only login (enterprise)

export MOG_CLIENT_SECRET="<client-secret-value>"

mog auth login \
  --profile work-app \
  --audience enterprise \
  --mode app-only \
  --client-id <enterprise-client-id> \
  --tenant <tenant-id-or-domain> \
  --app-only-user user@contoso.com \
  --client-secret-env MOG_CLIENT_SECRET

4) Switch and inspect profiles

mog auth accounts
mog auth use work
mog auth whoami

For one-off command routing without switching active profile:

mog --use-profile work mail list --max 10

5) Update existing auth settings without full re-onboarding

mog auth update
mog auth update --profile work

The update flow shows current settings, lets you choose one field at a time to edit, and saves only selected changes.

Command overview

  • mog auth
  • mog auth app
  • mog auth login|update|logout|accounts|use|whoami
  • mog mail list|get|send
  • mog calendar list|get|create|update|delete
  • mog contacts list|get|create|update|delete
  • mog groups list|get|members
  • mog tasks lists|list|get|create|update|complete|delete
  • mog onedrive ls|get|put|mkdir|rm
  • mog config get|keys|set|unset|list|path
  • mog completion <shell>

Usage examples

Mail:

mog mail list --max 50 --query "from:alerts@example.com"
mog mail get <message-id>
mog mail send --to dev@contoso.com --subject "Deploy complete" --body "Finished."
mog mail send --to dev@contoso.com --subject "Re: Deploy complete" --quote <message-id>
mog mail send --to dev@contoso.com --subject "Deploy complete" --body "Finished." --dry-run

Calendar:

mog calendar list --from 2026-02-12 --to 2026-02-19 --max 100
mog calendar create \
  --subject "Planning" \
  --start "2026-02-13T16:00:00-08:00" \
  --end "2026-02-13T16:30:00-08:00" \
  --body "Weekly sync"
mog calendar delete <event-id> --dry-run

Contacts:

mog contacts list --max 100
mog contacts create --display-name "Jane Doe" --email "jane@contoso.com"
mog contacts create \
  --display-name "Jane Doe" \
  --email "jane@contoso.com" \
  --org "Contoso" \
  --title "Program Manager" \
  --url "https://contoso.example/jane" \
  --note "Customer success lead" \
  --custom region=NA \
  --custom team=platform
mog contacts update <contact-id> --title "Director" --custom region=EMEA

Groups:

mog groups list --max 100
mog groups members <group-id> --max 100

Tasks:

mog tasks lists
mog tasks list --list <list-id> --max 100
mog tasks create --list <list-id> --title "Follow up"
mog tasks complete --list <list-id> --task <task-id>

OneDrive:

mog onedrive ls --path / --max 100
mog onedrive put ./report.pdf --path /Reports/report.pdf
mog onedrive get /Reports/report.pdf --out ./report.pdf
mog onedrive mkdir --path /Reports/Archive
mog onedrive rm --path /Reports/old-report.pdf
mog onedrive rm --path /Reports/old-report.pdf --dry-run

If mog onedrive get is run without --out, files are saved under the local onedrive-downloads directory in your mogcli config path.

App-only target user override (mail/contacts/onedrive):

mog mail list --user user@contoso.com --max 20
mog onedrive ls --user user@contoso.com --path /

Pagination and scripting

Most list commands support --page to resume from a next-page token.

mog groups list --max 50 --json
mog groups list --page "<next-token-url>"

--next-token is also accepted as an alias for pagination resume flags where supported.

Output modes:

  • --json: structured output for tooling.
  • --plain: stable tab-separated output for shell scripts.

Examples:

mog mail list --json | jq '.messages[0]'
mog tasks list --list <list-id> --plain

Configuration and secrets

Show config path:

mog config path

Show editable config keys:

mog config keys

Current keys:

  • timezone
  • keyring_backend

Profile metadata is stored in config. Tokens and secrets are stored via keychain/keyring backends.

keyring_backend supports auto, keychain, and file.

  • auto: use native OS keychain when available, otherwise file backend.
  • keychain: require native OS keychain support.
  • file: store under the local mogcli keyring directory.

MOG_KEYRING_PASSWORD is treated as explicitly configured even when empty, so headless runs do not implicitly prompt for keyring passwords.

Troubleshooting

No active profile:

mog auth accounts
mog auth use <profile>

Refresh delegated login:

mog auth login --profile <profile> --audience enterprise --client-id <id> --scope-workloads mail,calendar,contacts,tasks,onedrive

Logout and reset profile auth state:

mog auth logout --profile <profile>

Verbose mode:

mog --verbose mail list

Development

go test ./...
go run ./cmd/mog --help

Additional project docs are in docs/.

License

MIT