outlook-cli

outlook-cli

Production-ready CLI and MCP server for Microsoft Outlook through Microsoft Graph.

GitHub: https://github.com/selvin-paul-raj/outlook-cli

What This Package Gives You

• Global CLI command: outlook-cli
• One-time OAuth token storage — reused across runs and updates
• Human-friendly commands with rich terminal output, theme presets, and machine-friendly --json/--ai mode
• 21 MCP tools available to Claude and other AI assistants via the shared tool registry
• Full email, calendar, folder, and rules management through Microsoft Graph API

Install

Global (recommended)

npm i -g outlook-cli

outlook-cli --help

Local development

npm install
npm run cli -- --help

Requirements: Node.js >= 18.0.0

Azure App Setup (Required)

Before using this package you need an Azure app registration:

• Go to portal.azure.com → Azure Active Directory → App registrations → New registration
• Set redirect URI to: http://localhost:3333/auth/callback
• Under API Permissions, add Microsoft Graph delegated permissions:
  • Mail.Read, Mail.ReadWrite, Mail.Send
  • Calendars.Read, Calendars.ReadWrite
  • User.Read
  • offline_access
• Under Certificates & Secrets → New client secret — copy the Value (not the Secret ID)
• Copy your Application (client) ID from the Overview page

Quick Start

1. Set credentials

PowerShell (Windows):

$env:OUTLOOK_CLIENT_ID="your-client-id-here"
$env:OUTLOOK_CLIENT_SECRET="your-client-secret-value-here"

Bash/zsh (Linux/Mac):

export OUTLOOK_CLIENT_ID="your-client-id-here"
export OUTLOOK_CLIENT_SECRET="your-client-secret-value-here"

Or use a .env file (copy from .env.example):

cp .env.example .env
# Edit .env with your credentials

2. Start the auth server (required for first-time login)

npm run auth-server
# or
outlook-cli auth server --start

This starts an OAuth callback server on port 3333. Keep it running during authentication.

3. Authenticate once

outlook-cli auth login --open --start-server --wait

This opens your browser to the Microsoft login page. After you approve, tokens are saved to ~/.outlook-mcp-tokens.json and reused for all future runs.

4. Verify and explore

outlook-cli auth status        # confirm authenticated
outlook-cli tools list         # see all available tools
outlook-cli email list         # list recent inbox emails
outlook-cli calendar list      # list upcoming events

Environment Variables

Required

Variable	Description
OUTLOOK_CLIENT_ID	Azure app Application (client) ID
OUTLOOK_CLIENT_SECRET	Azure app client secret value (not the Secret ID)

Optional

Variable	Default	Description
OUTLOOK_REDIRECT_URI	http://localhost:3333/auth/callback	OAuth redirect URL
OUTLOOK_SCOPES	offline_access Mail.Read Mail.ReadWrite Mail.Send User.Read Calendars.Read Calendars.ReadWrite	Microsoft Graph permission scopes
OUTLOOK_TOKEN_STORE_PATH	~/.outlook-mcp-tokens.json	Where tokens are saved on disk
OUTLOOK_TOKEN_ENDPOINT	Microsoft consumer OAuth endpoint	Token exchange URL
OUTLOOK_AUTH_SERVER_URL	http://localhost:3333	Auth server base URL
USE_TEST_MODE	false	Use mock data instead of real API calls

Legacy aliases (backward-compatible): MS_CLIENT_ID, MS_CLIENT_SECRET, MS_REDIRECT_URI, MS_SCOPES, MS_TOKEN_STORE_PATH, MS_TOKEN_ENDPOINT, MS_AUTH_SERVER_URL

Command Groups

auth — Authentication

Command	Description	Example
auth status	Show current authentication status	outlook-cli auth status
auth login	Start authentication flow	outlook-cli auth login --open --start-server --wait
auth url	Show the OAuth URL without opening browser	outlook-cli auth url
auth server	Check/start local OAuth callback server	outlook-cli auth server --start
auth logout	Clear stored tokens	outlook-cli auth logout

Flags for auth login:

• --open — Automatically open the auth URL in your browser
• --start-server — Start the OAuth callback server automatically
• --wait — Wait for authentication to complete before returning
• --client-id — Provide Application (client) ID at runtime (optional)
• --client-secret — Provide client secret value at runtime (optional)
• --prompt-credentials — Prompt for missing credentials in interactive terminals

Examples:

# Full login with browser open and wait
outlook-cli auth login --open --start-server --wait

# Just get the URL to open manually
outlook-cli auth url

# Check if you're logged in
outlook-cli auth status

# Force re-authentication
outlook-cli auth login --open --force

# Runtime credentials (useful outside repo where .env is not loaded)
outlook-cli auth login --open --client-id <id> --client-secret <secret>

# Start or check auth callback server
outlook-cli auth server --start
outlook-cli auth server --status

email — Email Management

Command	Description	Example
email list	List recent emails	outlook-cli email list --count 20
email search	Search emails by criteria	outlook-cli email search --from [e-mail]
email read	Read full email content	outlook-cli email read --id AAMkAGVm...
email attachments	List attachments on one email	outlook-cli email attachments --id AAMkAGVm...
email attachment	Get one attachment and optionally save it	outlook-cli email attachment --id AAMkAGVm... --attachment-id AA... --save-path ./downloads/
email send	Send a new email	outlook-cli email send --to [e-mail] --subject "Hi" --body "Hello"
email mark-read	Mark email as read or unread	outlook-cli email mark-read --id AAMkAGVm...

email list — List Recent Emails

Lists emails from a folder, sorted newest first.

Parameters:

Flag	Type	Default	Description
--folder	string	inbox	Folder to list from: inbox, sent, drafts, deleted, junk, archive, or any custom folder name
--count	number	10	Number of emails to return (1–50)

Examples:

# Default: 10 most recent inbox emails
outlook-cli email list

# Last 25 inbox emails
outlook-cli email list --count 25

# 10 most recent sent emails
outlook-cli email list --folder sent

# 15 emails from a custom folder
outlook-cli email list --folder "Project Alpha" --count 15

# Output as JSON for scripting
outlook-cli email list --count 5 --json

Output shows: Email ID, sender, subject, date, read/unread status, attachment indicator, body preview.

email search — Search Emails

Searches emails using text and/or filter criteria. Supports multiple criteria simultaneously.

Parameters:

Flag	Type	Description
--query	string	Full-text search across subject, body, and sender
--folder	string	Folder to search (default: inbox)
--from	string	Filter by sender email or name
--to	string	Filter by recipient email
--subject	string	Filter by subject text
--hasAttachments	boolean	Only show emails with attachments
--unreadOnly	boolean	Only show unread emails
--count	number	Max results (1–50, default: 10)

Examples:

# Search by keyword
outlook-cli email search --query "quarterly report"

# Find unread emails from a specific sender
outlook-cli email search --from [e-mail] --unreadOnly

# Find emails with attachments about invoices
outlook-cli email search --subject invoice --hasAttachments

# Search sent folder for emails to a client
outlook-cli email search --folder sent --to [e-mail]

# Complex search
outlook-cli email search --from [e-mail] --subject "budget" --unreadOnly --count 20

# JSON output
outlook-cli email search --query "meeting notes" --json

email read — Read Full Email

Reads the complete content of one email by its ID.

Parameters:

Flag	Type	Required	Description
--id	string	yes	Email ID from email list or email search output

Examples:

# Read a specific email
outlook-cli email read --id AAMkAGVmMDAwAT...

# Read and output as JSON
outlook-cli email read --id AAMkAGVmMDAwAT... --json

Output shows: From, To, CC, BCC, Subject, Date, Importance, Attachment status, full Body text (HTML auto-converted to plain text).

Tip: Get email IDs from email list or email search output first.

email attachments — List Email Attachments

Lists attachments for a specific email message.

Parameters:

Flag	Type	Required	Default	Description
--id	string	yes	—	Message ID from email list or email search
--count	number	no	25	Max attachments to list (1–50)

Examples:

# List attachments for one message
outlook-cli email attachments --id AAMkAGVmMDAwAT...

# Limit to first 10 attachments
outlook-cli email attachments --id AAMkAGVmMDAwAT... --count 10

Output shows: Attachment ID, type (fileAttachment, itemAttachment, or referenceAttachment), content type, size, inline flag, and last modified date.

email attachment — Get/Download One Attachment

Gets metadata for one attachment and optionally saves it to disk.

Parameters:

Flag	Type	Required	Default	Description
--id	string	yes	—	Message ID
--attachmentId	string	yes	—	Attachment ID from email attachments
--savePath	string	no	—	File path or directory path to save downloaded bytes
--includeContent	boolean	no	false	Include text preview when attachment content is text-like
--expandItem	boolean	no	false	Expand metadata for item attachments
--overwrite	boolean	no	false	Overwrite existing file at destination path

Examples:

# Get metadata only
outlook-cli email attachment --id AAMkAGVmMDAwAT... --attachment-id AAMkAGVmMDAwAT...=

# Save attachment to downloads directory
outlook-cli email attachment \
  --id AAMkAGVmMDAwAT... \
  --attachment-id AAMkAGVmMDAwAT...= \
  --save-path ./downloads/

# Save and include text preview when possible
outlook-cli email attachment \
  --id AAMkAGVmMDAwAT... \
  --attachment-id AAMkAGVmMDAwAT...= \
  --save-path ./downloads/ \
  --include-content

Notes:

• referenceAttachment is a cloud link and cannot be downloaded as raw bytes from this endpoint.
• Item attachments use MIME raw content when downloaded.

email send — Send Email

Composes and sends an email from the user's account.

Parameters:

Flag	Type	Required	Default	Description
--to	string	yes	—	Recipient(s), comma-separated for multiple
--subject	string	yes	—	Email subject
--body	string	yes	—	Email body (plain text or HTML)
--cc	string	no	—	CC recipient(s), comma-separated
--bcc	string	no	—	BCC recipient(s), comma-separated
--importance	string	no	normal	Priority: normal, high, or low
--saveToSentItems	boolean	no	true	Save copy to Sent folder

Examples:

# Simple email
outlook-cli email send \
  --to [e-mail] \
  --subject "Meeting notes" \
  --body "Here are today's action items..."

# Email to multiple recipients with CC and high priority
outlook-cli email send \
  --to "[e-mail],[e-mail]" \
  --cc [e-mail] \
  --subject "URGENT: System outage" \
  --body "We are investigating..." \
  --importance high

# Email without saving to sent folder
outlook-cli email send \
  --to [e-mail] \
  --subject "Test" \
  --body "Hello" \
  --saveToSentItems false

Notes:

• HTML body is detected automatically when the body contains <html.
• Sending attachments is not supported yet — body text only.

email mark-read — Mark Email Read/Unread

Changes the read status of an email.

Parameters:

Flag	Type	Required	Default	Description
--id	string	yes	—	Email ID
--isRead	boolean	no	true	true = mark read, false = mark unread

Examples:

# Mark as read (default)
outlook-cli email mark-read --id AAMkAGVmMDAwAT...

# Mark as unread
outlook-cli email mark-read --id AAMkAGVmMDAwAT... --isRead false

calendar — Calendar Management

Command	Description
calendar list	List upcoming events
calendar create	Create a new event
calendar decline	Decline an event invitation
calendar cancel	Cancel an event you organized
calendar delete	Delete an event

calendar list — List Upcoming Events

Lists upcoming calendar events starting from now, ordered by start time.

Parameters:

Flag	Type	Default	Description
--count	number	10	Number of events to return (1–50)

Examples:

# Next 10 events (default)
outlook-cli calendar list

# Next 30 events
outlook-cli calendar list --count 30

# JSON output
outlook-cli calendar list --count 5 --json

Output shows: Event ID, subject, location, start time, end time, organizer, attendees list.

Tip: Copy the Event ID from the output to use with decline, cancel, or delete commands.

calendar create — Create Calendar Event

Creates a new event on the calendar. Optionally invites attendees.

Parameters:

Flag	Type	Required	Description
--subject	string	yes	Event title
--start	string	yes	Start datetime: YYYY-MM-DDTHH:MM:SS
--end	string	yes	End datetime: YYYY-MM-DDTHH:MM:SS
--attendees	string	no	Comma-separated attendee email addresses
--body	string	no	Event description/agenda

Examples:

# Simple personal event
outlook-cli calendar create \
  --subject "Focus time" \
  --start "2026-04-10T09:00:00" \
  --end "2026-04-10T11:00:00"

# Team meeting with attendees and agenda
outlook-cli calendar create \
  --subject "Q2 Planning" \
  --start "2026-04-15T14:00:00" \
  --end "2026-04-15T15:30:00" \
  --attendees "[e-mail],[e-mail]" \
  --body "Agenda: review Q1, plan Q2 roadmap, assign owners"

# All-day event (use midnight to midnight)
outlook-cli calendar create \
  --subject "Company holiday" \
  --start "2026-04-25T00:00:00" \
  --end "2026-04-25T23:59:00"

Notes:

• Datetime must be in YYYY-MM-DDTHH:MM:SS format without timezone offset.
• The server uses Central European Standard Time by default.

calendar decline — Decline Event Invitation

Declines a received event invitation, optionally with a message to the organizer.

Parameters:

Flag	Type	Required	Description
--eventId	string	yes	Event ID from calendar list
--comment	string	no	Message to send to the organizer

Examples:

# Decline without a message
outlook-cli calendar decline --eventId AAMkAGVmMDAwAT...

# Decline with a reason
outlook-cli calendar decline \
  --eventId AAMkAGVmMDAwAT... \
  --comment "Sorry, I have a conflict. Can we reschedule to next week?"

calendar cancel — Cancel Your Event

Cancels an event you organized and notifies all attendees.

Parameters:

Flag	Type	Required	Description
--eventId	string	yes	Event ID from calendar list
--comment	string	no	Cancellation reason sent to attendees

Examples:

# Cancel without message
outlook-cli calendar cancel --eventId AAMkAGVmMDAwAT...

# Cancel with explanation
outlook-cli calendar cancel \
  --eventId AAMkAGVmMDAwAT... \
  --comment "This meeting is no longer needed. Details will follow by email."

Note: Use cancel (not delete) when you want attendees to receive a cancellation notification.

calendar delete — Delete Event

Permanently removes an event from the calendar without notifying attendees.

Parameters:

Flag	Type	Required	Description
--eventId	string	yes	Event ID from calendar list

Examples:

outlook-cli calendar delete --eventId AAMkAGVmMDAwAT...

Tip: Use cancel instead of delete for meetings with attendees so they receive proper notification.

folder — Mail Folder Management

Command	Description
folder list	List all mail folders
folder create	Create a new folder
folder move	Move emails to another folder

folder list — List Mail Folders

Lists all mail folders in the account. Optionally shows item counts and subfolder hierarchy.

Parameters:

Flag	Type	Default	Description
--includeItemCounts	boolean	false	Show total and unread message counts
--includeChildren	boolean	false	Show nested subfolders

Examples:

# Simple folder list
outlook-cli folder list

# With message counts
outlook-cli folder list --includeItemCounts

# Full hierarchy with counts
outlook-cli folder list --includeItemCounts --includeChildren

# JSON output for scripting
outlook-cli folder list --includeItemCounts --json

Tip: Use this to discover custom folder names before using them in email list, email search, folder move, or rule create.

folder create — Create Mail Folder

Creates a new mail folder at the root level or inside an existing folder.

Parameters:

Flag	Type	Required	Default	Description
--name	string	yes	—	Name for the new folder
--parentFolder	string	no	root	Name of existing parent folder

Examples:

# Create top-level folder
outlook-cli folder create --name "Project Alpha"

# Create subfolder inside an existing folder
outlook-cli folder create --name "2026 Invoices" --parentFolder "Finance"

# Create a subfolder under inbox
outlook-cli folder create --name "Action Required" --parentFolder inbox

folder move — Move Emails

Moves one or more emails from one folder to another.

Parameters:

Flag	Type	Required	Default	Description
--emailIds	string	yes	—	Comma-separated email ID(s)
--targetFolder	string	yes	—	Destination folder name
--sourceFolder	string	no	inbox	Source folder (for context)

Examples:

# Move one email to archive
outlook-cli folder move \
  --emailIds AAMkAGVmMDAwAT... \
  --targetFolder archive

# Move multiple emails to a custom folder
outlook-cli folder move \
  --emailIds "AAMkAGVm...,BBMkAHXn...,CCMkAIYo..." \
  --targetFolder "Project Alpha"

# Move from a non-inbox folder
outlook-cli folder move \
  --emailIds AAMkAGVmMDAwAT... \
  --sourceFolder "Junk" \
  --targetFolder inbox

Output: Reports success count, failure count, and error details for any failed moves (up to 3 error messages shown).

rule — Inbox Rules

Command	Description
rule list	List all inbox rules
rule create	Create a new inbox rule
rule sequence	Change a rule's execution order

rule list — List Inbox Rules

Lists all inbox rules sorted by sequence (execution order — lower runs first).

Parameters:

Flag	Type	Default	Description
--includeDetails	boolean	false	Show full conditions and actions

Examples:

# Just rule names and enabled status
outlook-cli rule list

# Full detail — conditions and actions for each rule
outlook-cli rule list --includeDetails

# JSON for scripting
outlook-cli rule list --includeDetails --json

Output (with details) shows:

• Conditions: fromAddresses, subjectContains, bodyContains, hasAttachment, importance
• Actions: moveToFolder, copyToFolder, markAsRead, markImportance, forwardTo, delete

rule create — Create Inbox Rule

Creates an inbox rule that automatically processes incoming emails. Needs a name, at least one condition, and at least one action.

Parameters:

Flag	Type	Required	Description
--name	string	yes	Rule name
--fromAddresses	string	condition	Comma-separated sender emails to match
--containsSubject	string	condition	Text that must appear in subject
--hasAttachments	boolean	condition	Match only emails with attachments
--moveToFolder	string	action	Folder name to move matching emails to
--markAsRead	boolean	action	Auto-mark matching emails as read
--isEnabled	boolean	—	Whether rule is active (default: true)
--sequence	number	—	Execution order (lower = first); auto-assigned if omitted

At least one condition (--fromAddresses, --containsSubject, --hasAttachments) and at least one action (--moveToFolder, --markAsRead) are required.

Examples:

# Auto-move emails from boss to Important folder
outlook-cli rule create \
  --name "Boss emails" \
  --fromAddresses [e-mail] \
  --moveToFolder Important

# Auto-file newsletters and mark as read
outlook-cli rule create \
  --name "Newsletter handler" \
  --fromAddresses "[e-mail],[e-mail]" \
  --moveToFolder Newsletters \
  --markAsRead \
  --sequence 10

# Rule based on subject text
outlook-cli rule create \
  --name "Invoice sorter" \
  --containsSubject invoice \
  --hasAttachments \
  --moveToFolder Finance

# Disabled rule (create but don't activate yet)
outlook-cli rule create \
  --name "Temp filter" \
  --fromAddresses [e-mail] \
  --markAsRead \
  --isEnabled false

Notes:

• The moveToFolder target must already exist. Create it first with folder create.
• If --sequence is not provided, the rule is placed after all existing rules.

rule sequence — Change Rule Execution Order

Changes the sequence (execution order) of an existing rule. Lower sequence numbers run first.

Parameters:

Flag	Type	Required	Description
--ruleName	string	yes	Exact name of the rule to reorder
--sequence	number	yes	New sequence number

Examples:

# Make boss email rule run first
outlook-cli rule sequence --ruleName "Boss emails" --sequence 1

# Push newsletter rule later in the order
outlook-cli rule sequence --ruleName "Newsletter handler" --sequence 500

tools — Tool Inspection

Command	Description	Example
tools list	List all available MCP tools	outlook-cli tools list
tools schema	Show schema for a specific tool	outlook-cli tools schema list-emails

Examples:

# See all tools
outlook-cli tools list

# Inspect a tool's parameters
outlook-cli tools schema send-email
outlook-cli tools schema create-event

call — Generic Tool Invocation

Invoke any MCP tool directly by name with JSON arguments.

outlook-cli call <tool-name> --args-json '<json>'

Examples:

# List emails via generic call
outlook-cli call list-emails --args-json '{"folder":"inbox","count":5}'

# Send email via generic call
outlook-cli call send-email --args-json '{"to":"[e-mail]","subject":"Hi","body":"Hello"}'

# With JSON output
outlook-cli call list-events --args-json '{"count":10}' --json

agents — AI Agent Guide

Shows best-practice command flow for AI agents (Claude, Codex, VS Code, automation scripts).

outlook-cli agents guide

Agent workflow (recommended):

outlook-cli auth status --json
outlook-cli tools list --json
outlook-cli tools schema send-email --json
outlook-cli call list-emails --args-json '{"folder":"inbox","count":5}' --ai

doctor — Diagnostics

Runs a series of diagnostic checks and reports what's working and what needs fixing.

outlook-cli doctor

Checks: Node.js version, environment variables, token file presence, token validity, server connectivity.

update — Update the CLI

# Check for updates
outlook-cli update

# Run the update automatically
outlook-cli update --run

Or update via npm directly:

npm i -g outlook-cli@latest

Output Flags (All Commands)

Flag	Description
--json	Output raw JSON instead of human-readable text
--ai	Agent-safe alias for JSON mode (suppresses rich UI output)
`--theme k9s	ocean
--plain	No colors or formatting
--no-color	Disable color only
--no-animate	Disable spinner animations

In JSON mode, responses include both:

• result (original MCP tool payload)
• structured (normalized machine-friendly fields like summary, items, and parsed metadata)

Examples:

outlook-cli auth status --json
outlook-cli tools list --ai
outlook-cli email list --count 10 --json
outlook-cli --theme ocean --help
outlook-cli calendar list --plain

Complete MCP Tool Catalog

All 21 tools are available through the shared MCP tool registry — used by Claude and other AI assistants, and also callable via outlook-cli call <tool-name>.

Authentication Tools

Tool	What it does	Required	Optional
about	Returns server name, version, description	none	none
authenticate	Starts OAuth flow, returns auth URL	none	force (boolean)
check-auth-status	Returns current auth status	none	none

Calendar Tools

Tool	What it does	Required	Optional
list-events	List upcoming calendar events	none	count (1–50)
create-event	Create a new event	subject, start, end	attendees (array), body
decline-event	Decline an event invitation	eventId	comment
cancel-event	Cancel an event and notify attendees	eventId	comment
delete-event	Delete an event silently	eventId	none

Email Tools

Tool	What it does	Required	Optional
list-emails	List recent emails from a folder	none	folder, count
search-emails	Search with text and filter criteria	none	query, folder, from, to, subject, hasAttachments, unreadOnly, count
read-email	Read full content of one email	id	none
list-attachments	List attachments on a message	messageId	count
get-attachment	Get one attachment metadata and optionally download it	messageId, attachmentId	savePath, includeContent, expandItem, overwrite
send-email	Send a new email	to, subject, body	cc, bcc, importance, saveToSentItems
mark-as-read	Mark email read or unread	id	isRead (boolean, default true)

Folder Tools

Tool	What it does	Required	Optional
list-folders	List all mail folders	none	includeItemCounts, includeChildren
create-folder	Create a new folder	name	parentFolder
move-emails	Move emails to another folder	emailIds (comma-separated), targetFolder	sourceFolder

Rules Tools

Tool	What it does	Required	Optional
list-rules	List inbox rules by execution order	none	includeDetails
create-rule	Create inbox rule (1 condition + 1 action minimum)	name + condition + action	isEnabled, sequence
edit-rule-sequence	Change rule execution order	ruleName, sequence	none

MCP Server Mode (for Claude and AI Assistants)

Run as a standard MCP stdio server for use with Claude Desktop or other MCP clients:

npm run mcp-server
# or
node index.js

Claude Desktop Configuration

Add to your Claude Desktop config file (claude-config-sample.json is included as a reference):

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/path/to/outlook-mcp/index.js"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "outlook": {
      "command": "outlook-cli",
      "args": ["mcp-server"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

AI Assistant Skill

A complete skill reference for AI assistants (Claude and others) is in skill/outlook-mcp.md. This document covers every tool, every parameter, common workflows, and examples — useful for RAG systems or as a system prompt addition.

Token Behavior

• Tokens are stored at ~/.outlook-mcp-tokens.json (Windows: %USERPROFILE%\.outlook-mcp-tokens.json)
• Tokens survive package updates and reinstalls — no need to re-authenticate after upgrading
• Access tokens auto-refresh when expired (using the refresh token)
• Force re-authentication anytime with outlook-cli auth login --force or authenticate { force: true }

Test Mode

USE_TEST_MODE=true outlook-cli email list

With USE_TEST_MODE=true, all API calls use mock data — no real Microsoft account needed. Useful for development and CI testing.

Troubleshooting

Problem	Solution
AADSTS7000215 error	You're using the Secret ID instead of the secret Value in Azure
Auth server won't start	Run npx kill-port 3333 then try again
"Not authenticated" after token exists	Token expired with no refresh token — run auth login again
create-rule fails on folder	Folder doesn't exist — run folder create first
move-emails partial failure	Some email IDs were invalid — verify IDs with email list
Missing dependencies	Run npm install

AI Assistant Skill

The skills/outlook-automation/ folder contains a structured skill for Claude Code, OpenAI Codex, and VS Code.

Install the skill

# Claude Code — personal
uv run python tools/install_skill.py --personal

# Claude Code — project/team
uv run python tools/install_skill.py --project

# OpenAI Codex
uv run python tools/install_skill.py --codex

# Verify
uv run python tools/install_skill.py --verify --personal

Note: OpenAI Codex skills require the experimental feature flag. Add to ~/.codex/config.toml:

[features]
skills = true

Skill structure

File	Contents
skills/outlook-automation/SKILL.md	Main skill entry — overview, behavioral rules, quick examples, install instructions
skills/outlook-automation/reference/cli.md	Complete CLI command reference — every command, flag, and example
skills/outlook-automation/reference/json-schema.md	JSON schemas for all 21 MCP tools
skills/outlook-automation/reference/security.md	OAuth flow, token lifecycle, permission scopes, AI safety rules
skills/outlook-automation/reference/troubleshooting.md	Common errors, diagnostic checklist, step-by-step fixes

Documentation

File	Contents
docs/REFERENCE.md	Full parameter-by-parameter API reference
CLI.md	CLI quick reference card
QUICKSTART.md	Setup walkthrough for new users
docs/PROJECT-STRUCTURE.md	Codebase architecture and module overview
docs/PUBLISHING.md	Publishing checklist for maintainers
claude-config-sample.json	Sample Claude Desktop MCP config

Scripts Reference

Script	Command	Description
npm start	node cli.js	Run the CLI
npm run mcp-server	node index.js	Run as MCP stdio server
npm run cli	node cli.js	CLI alias
npm run auth-server	node outlook-auth-server.js	Start OAuth callback server on port 3333
npm run doctor	node cli.js doctor	Run diagnostics
npm run inspect	MCP Inspector	Test MCP server interactively
npm test	Jest	Run unit tests