msgraph-cli

Command-line interface for the Microsoft Graph API. 55 commands across 9 domains — Teams chats, messages, mail, calendar, users, files, rooms, and transcripts.

Install

npm install -g msgraph-cli

Setup

Register an app in Azure AD and set:

export MSGRAPH_CLIENT_ID="your-azure-app-client-id"
export MSGRAPH_TENANT_ID="your-azure-tenant-id"
export MSGRAPH_CLIENT_SECRET="your-client-secret"    # required for browser login only

Then log in:

msgraph login                # opens browser (PKCE + account picker)
msgraph login --device-code  # for headless/SSH environments

The token is stored at ~/.config/msgraph-cli/token.json and auto-refreshes.

Commands

All commands output JSON. Add --pretty to pretty-print.

auth

| Command | Description | |---------|-------------| | msgraph login | Authenticate via browser or --device-code | | msgraph logout | Clear stored token | | msgraph status | Show current auth status |

user

| Command | Description | |---------|-------------| | msgraph user me | Get current user profile | | msgraph user get <userId> | Get a user by ID or email | | msgraph user search <query> | Search users by name | | msgraph user photo <userId> | Download user photo | | msgraph user set-status | Set presence status message |

chat

| Command | Description | |---------|-------------| | msgraph chat get <chatId> | Get chat details | | msgraph chat search --member <name\|email> | Find chats with a person (DM + group chats) | | msgraph chat search --topic <text> | Find chats by topic | | msgraph chat create | Create a new chat | | msgraph chat update <chatId> | Update chat topic | | msgraph chat mark-read <chatId> | Mark chat as read | | msgraph chat mark-unread <chatId> | Mark chat as unread | | msgraph chat add-member <chatId> <userId> | Add a member | | msgraph chat remove-member <chatId> <membershipId> | Remove a member |

message

| Command | Description | |---------|-------------| | msgraph message list <chatId> | List messages in a chat (--since, --containing, --from-user) | | msgraph message get <chatId> <messageId> | Get a specific message | | msgraph message send <chatId> | Send a message (--format: text/markdown) | | msgraph message update <chatId> <messageId> | Edit a message | | msgraph message delete <chatId> <messageId> | Soft-delete a message | | msgraph message undelete <chatId> <messageId> | Restore a soft-deleted message | | msgraph message search [query] | Search messages across all chats (--from, --unread, --sent-after) | | msgraph message react <chatId> <messageId> <emoji> | Add reaction (Unicode emoji) | | msgraph message unreact <chatId> <messageId> <emoji> | Remove reaction |

mail

| Command | Description | |---------|-------------| | msgraph mail list | List messages (--folder accepts well-known names, custom names, paths, or ids) | | msgraph mail get <messageId> | Get an email | | msgraph mail search <query> | Search emails (KQL) | | msgraph mail send | Send an email | | msgraph mail reply <messageId> | Reply to an email | | msgraph mail forward <messageId> | Forward an email | | msgraph mail mark-read <messageId> | Mark as read | | msgraph mail move <messageId> --to <folder> | Move a message; returns the rotated id | | msgraph mail copy <messageId> --to <folder> | Copy a message into a folder | | msgraph mail delete <messageId> | Delete an email |

mail folder

| Command | Description | |---------|-------------| | msgraph mail folder list [--tree] | List folders, optionally one level of children | | msgraph mail folder create <name> [--parent <name\|id>] | Create at root or under a parent | | msgraph mail folder rename <folder> <newName> | Rename a folder | | msgraph mail folder move <folder> --to <parent> | Reparent a folder (id rotates) | | msgraph mail folder delete <folder> | Delete (moves to Deleted Items) |

mail rule (inbox rules)

| Command | Description | |---------|-------------| | msgraph mail rule list | List inbox rules | | msgraph mail rule get <ruleId> | Get a single rule | | msgraph mail rule create --name <X> [conditions] [actions] | Create a rule (rich flag set + JSON escape hatches) | | msgraph mail rule update <ruleId> [...] | Patch any subset of fields | | msgraph mail rule enable\|disable <ruleId> | Toggle without deleting | | msgraph mail rule delete <ruleId> | Hard delete |

calendar

| Command | Description | |---------|-------------| | msgraph calendar events | List upcoming events (--limit, --start, --end) | | msgraph calendar create | Create an event | | msgraph calendar update <eventId> | Update an event | | msgraph calendar respond <eventId> <response> | Accept, decline, or tentatively accept | | msgraph calendar cancel <eventId> | Cancel an event you organized | | msgraph calendar find-times | Find available meeting times for attendees | | msgraph calendar get-schedule | Get free/busy schedule for users |

room

| Command | Description | |---------|-------------| | msgraph room list | List meeting rooms |

transcript

| Command | Description | |---------|-------------| | msgraph transcript list <meetingId> | List transcripts for a meeting | | msgraph transcript get <meetingId> <transcriptId> | Get transcript content |

file

| Command | Description | |---------|-------------| | msgraph file get <driveItemId> | Get file metadata | | msgraph file download <driveItemId> | Download a file from OneDrive | | msgraph file download-hosted <driveItemId> | Download a hosted file (e.g., OneNote as PDF) | | msgraph file search <query> | Search OneDrive files | | msgraph file upload <localPath> | Upload a file to OneDrive | | msgraph file update <driveItemId> | Update file content | | msgraph file grant <driveItemId> | Create a sharing link |

Pagination

Every list command uses caller-driven pagination. Responses include a nextPage field — pass it back as --start to fetch the next page. When nextPage is null, there are no more results. The CLI never loops through pages internally.

Examples

# Check auth status
msgraph status

# Look up a colleague
msgraph user search "Jane Smith"
msgraph user get [email protected]

# Find your DM with someone (email is faster than name)
msgraph chat search --member [email protected]

# Find a group chat by topic
msgraph chat search --topic "Project Alpha"

# Read recent messages
msgraph message list 19:[email protected] --limit 10

# Search messages across all chats
msgraph message search "deployment issue" --from "Bob" --sent-after 2026-04-01

# Send a message
msgraph message send 19:[email protected] --body "Deploying now" --format text

# React to a message
msgraph message react 19:[email protected] 1234567890 👍

# List today's calendar
msgraph calendar events --limit 10

# Find a meeting time with colleagues
msgraph calendar find-times --attendees "[email protected],[email protected]" --duration 30

# Check room availability
msgraph calendar get-schedule --schedules "[email protected]" --start-date 2026-04-14T09:00 --end-date 2026-04-14T17:00

# Search emails
msgraph mail search "from:[email protected] subject:urgent"

# Send an email
msgraph mail send --to "[email protected]" --subject "Update" --body "All systems go"

# Upload a file to OneDrive
msgraph file upload ./report.pdf --path /Reports/Q2/

# Search OneDrive
msgraph file search "quarterly report"

Authentication Details

The CLI supports multiple auth flows for different environments:

| Flow | When to use | Command / Variable | |------|-------------|-------------------| | Browser (default) | Interactive terminal with browser access | msgraph login | | Device code | Headless / SSH environments | msgraph login --device-code | | Direct token | Pre-obtained token (no refresh) | MICROSOFT_ACCESS_TOKEN | | OAuth proxy | Centralized token management | MICROSOFT_OAUTH_URL |

Browser and device-code flows store a refresh token at ~/.config/msgraph-cli/token.json that auto-refreshes on expiry. Direct token and OAuth proxy are stateless — no token file is written.

Environment variables also accept the MICROSOFT_* prefix (e.g., MICROSOFT_CLIENT_ID) as an alias for MSGRAPH_*.