outlook-cli 1.2.1 → 1.2.3

package/CLI.md

@@ -13,7 +13,9 @@ outlook-cli --help
 ## Global options
 
 - `--json`
+- `--ai`
 - `--output text|json`
+- `--theme k9s|ocean|mono`
 - `--plain`
 - `--no-color`
 - `--no-animate`
@@ -34,15 +36,28 @@ outlook-cli tools schema send-email
 outlook-cli auth status
 outlook-cli auth url
 outlook-cli auth login --open --start-server --wait --timeout 180
+outlook-cli auth login --open --client-id <id> --client-secret <secret>
+outlook-cli auth server --start
+outlook-cli auth server --status
 outlook-cli auth logout
 ```
 
+## AI Agents
+
+```bash
+outlook-cli agents guide
+outlook-cli tools list --ai
+outlook-cli call list-emails --args-json '{"folder":"inbox","count":5}' --ai
+```
+
 ## Email
 
 ```bash
 outlook-cli email list --folder inbox --count 20
 outlook-cli email search --query "invoice" --unread-only true --count 10
 outlook-cli email read --id <message-id>
+outlook-cli email attachments --id <message-id>
+outlook-cli email attachment --id <message-id> --attachment-id <attachment-id> --save-path ./downloads/
 outlook-cli email send --to jane@example.com --subject "Status" --body "Done"
 outlook-cli email mark-read --id <message-id> --is-read true
 ```
@@ -86,4 +101,5 @@ outlook-cli call create-event --args-json '{"subject":"Standup","start":"2026-04
 outlook-cli doctor
 outlook-cli update
 outlook-cli update --run
+outlook-cli mcp-server
 ```

package/README.md

@@ -10,8 +10,8 @@ Production-ready CLI and MCP server for Microsoft Outlook through Microsoft Grap
 
 - Global CLI command: `outlook-cli`
 - One-time OAuth token storage — reused across runs and updates
-- Human-friendly commands with rich terminal output, plus machine-friendly `--json` mode
-- 19 MCP tools available to Claude and other AI assistants via the shared tool registry
+- 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
 
 ---
@@ -139,12 +139,16 @@ outlook-cli calendar list      # list upcoming events
 | `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:**
 ```bash
@@ -159,6 +163,13 @@ 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
 ```
 
 ---
@@ -170,6 +181,8 @@ outlook-cli auth login --open --force
 | `email list` | List recent emails | `outlook-cli email list --count 20` |
 | `email search` | Search emails by criteria | `outlook-cli email search --from boss@company.com` |
 | `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 user@example.com --subject "Hi" --body "Hello"` |
 | `email mark-read` | Mark email as read or unread | `outlook-cli email mark-read --id AAMkAGVm...` |
 
@@ -273,6 +286,70 @@ outlook-cli email read --id AAMkAGVmMDAwAT... --json
 
 ---
 
+#### `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:**
+```bash
+# 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:**
+```bash
+# 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.
@@ -315,7 +392,7 @@ outlook-cli email send \
 
 **Notes:**
 - HTML body is detected automatically when the body contains `<html`.
-- Attachments are not supported — body text only.
+- Sending attachments is not supported yet — body text only.
 
 ---
 
@@ -750,6 +827,24 @@ 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).
+
+```bash
+outlook-cli agents guide
+```
+
+**Agent workflow (recommended):**
+```bash
+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.
@@ -784,14 +879,22 @@ npm i -g outlook-cli@latest
 | 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|mono` | Select color theme for text output |
 | `--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:**
 ```bash
 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
 ```
 
@@ -799,7 +902,7 @@ outlook-cli calendar list --plain
 
 ## Complete MCP Tool Catalog
 
-All 19 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>`.
+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
 
@@ -826,6 +929,8 @@ All 19 tools are available through the shared MCP tool registry — used by Clau
 | `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`) |
 
@@ -962,7 +1067,7 @@ uv run python tools/install_skill.py --verify --personal
 |---|---|
 | [skills/outlook-automation/SKILL.md](skills/outlook-automation/SKILL.md) | Main skill entry — overview, behavioral rules, quick examples, install instructions |
 | [skills/outlook-automation/reference/cli.md](skills/outlook-automation/reference/cli.md) | Complete CLI command reference — every command, flag, and example |
-| [skills/outlook-automation/reference/json-schema.md](skills/outlook-automation/reference/json-schema.md) | JSON schemas for all 19 MCP tools |
+| [skills/outlook-automation/reference/json-schema.md](skills/outlook-automation/reference/json-schema.md) | JSON schemas for all 21 MCP tools |
 | [skills/outlook-automation/reference/security.md](skills/outlook-automation/reference/security.md) | OAuth flow, token lifecycle, permission scopes, AI safety rules |
 | [skills/outlook-automation/reference/troubleshooting.md](skills/outlook-automation/reference/troubleshooting.md) | Common errors, diagnostic checklist, step-by-step fixes |