outlook-cli 1.2.0

package/docs/REFERENCE.md

@@ -0,0 +1,679 @@
+# CLI and MCP Tool Reference
+
+This document is the complete, publish-ready reference for:
+
+- every CLI command and subcommand
+- every parameter, required field, default, and behavior
+- every MCP tool input schema exposed through the tool registry
+
+## Conventions
+
+- CLI binary: `outlook-cli`
+- Output mode:
+  - `text` (default)
+  - `json` (with `--json` or `--output json`)
+- Option key normalization:
+  - `--event-id` and `--eventId` map to the same internal key.
+  - `--start-server` and `--startServer` are equivalent.
+- Boolean parsing accepts:
+  - true values: `true`, `1`, `yes`, `y`, `on`
+  - false values: `false`, `0`, `no`, `n`, `off`
+
+## Global CLI options
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--json` | boolean | No | `false` | Forces JSON output for automation and agents. |
+| `--output` | `text` \| `json` | No | `text` | Explicit output mode override. |
+| `--plain` | boolean | No | `false` | Disables rich color and animation UI output. |
+| `--no-color` | boolean | No | `false` | Disables terminal colors. |
+| `--no-animate` | boolean | No | `false` | Disables loading/waiting spinner animation. |
+| `--help`, `-h` | boolean | No | `false` | Prints usage information. |
+| `--version`, `-v` | boolean | No | `false` | Prints package version. |
+
+## Top-level commands
+
+| Command | Description |
+|---|---|
+| `commands` | Prints command groups and all registered MCP tools. |
+| `-commands` / `--commands` | Alias to `commands`. |
+| `tools list` | Lists all tools with descriptions and schemas. |
+| `tools schema <tool-name>` | Prints schema for one tool. |
+| `call <tool-name>` | Calls any registered MCP tool directly. |
+| `auth ...` | Authentication command group. |
+| `email ...` | Email command group. |
+| `calendar ...` | Calendar command group. |
+| `folder ...` | Folder command group. |
+| `rule ...` | Rules command group. |
+| `doctor` | Environment and auth diagnostics. |
+| `update` | Prints or runs global npm update command. |
+| `help` | Same as `--help`. |
+| `version` | Same as `--version`. |
+
+## Command details
+
+### commands
+
+Prints:
+
+- command groups
+- registered tool count
+- tool names, descriptions, and input schemas (in JSON mode)
+
+Examples:
+
+```bash
+outlook-cli commands
+outlook-cli commands --json
+outlook-cli -commands --json
+```
+
+### tools list
+
+Lists all registered tools.
+
+Examples:
+
+```bash
+outlook-cli tools list
+outlook-cli tools list --json
+```
+
+### tools schema
+
+Usage:
+
+```bash
+outlook-cli tools schema <tool-name>
+```
+
+Parameters:
+
+| Parameter | Type | Required | Description |
+|---|---|---:|---|
+| `<tool-name>` | string | Yes | Exact MCP tool name, for example `send-email`. |
+
+### call
+
+Usage:
+
+```bash
+outlook-cli call <tool-name> [--args-json '{...}'] [--arg key=value]
+```
+
+Parameters:
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `<tool-name>` | string | Yes | - | Exact MCP tool name. |
+| `--args-json` | object JSON | No | `{}` | Base arguments object. Must be valid JSON object. |
+| `--arg` | repeated `key=value` | No | none | Additional args. Repeated flags are merged. |
+
+Merge behavior:
+
+- `--arg` keys overwrite the same key from `--args-json`.
+
+Examples:
+
+```bash
+outlook-cli call list-emails --args-json '{"count":5}'
+outlook-cli call search-emails --arg query=invoice --arg unreadOnly=true --json
+```
+
+### auth status
+
+Shows current auth state and token file path.
+
+Usage:
+
+```bash
+outlook-cli auth status
+```
+
+### auth url
+
+Prints the Microsoft OAuth URL generated from current config.
+
+Usage:
+
+```bash
+outlook-cli auth url
+```
+
+### auth login
+
+Starts and/or opens auth flow and optionally waits for token.
+
+Usage:
+
+```bash
+outlook-cli auth login [options]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--force` | boolean | No | `false` | Clears cached token and forces re-authentication. |
+| `--open` | boolean | No | `true` | Opens auth URL in default browser. |
+| `--start-server` | boolean | No | `true` | Starts local auth server if not already running. |
+| `--wait` | boolean | No | `true` | Waits for token completion before returning. |
+| `--timeout` | number (seconds) | No | `180` | Max wait time when `--wait` is true. Min effective timeout is 5s. |
+
+### auth logout
+
+Clears token cache from token store path.
+
+Usage:
+
+```bash
+outlook-cli auth logout
+```
+
+### email list
+
+Maps to tool: `list-emails`
+
+Usage:
+
+```bash
+outlook-cli email list [options]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--folder` | string | No | `inbox` | Folder name. |
+| `--count` | number | No | `10` | Max number of messages to return. |
+
+### email search
+
+Maps to tool: `search-emails`
+
+Usage:
+
+```bash
+outlook-cli email search [options]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--query` | string | No | empty | Full-text search text. |
+| `--folder` | string | No | `inbox` | Folder to search. |
+| `--from` | string | No | empty | Sender filter. |
+| `--to` | string | No | empty | Recipient filter. |
+| `--subject` | string | No | empty | Subject filter. |
+| `--has-attachments` | boolean | No | unset | If true, only emails with attachments. |
+| `--unread-only` | boolean | No | unset | If true, only unread emails. |
+| `--count` | number | No | `10` | Max results. |
+
+### email read
+
+Maps to tool: `read-email`
+
+Usage:
+
+```bash
+outlook-cli email read --id <email-id>
+```
+
+Options:
+
+| Option | Type | Required | Description |
+|---|---|---:|---|
+| `--id` | string | Yes | Message ID. |
+
+### email send
+
+Maps to tool: `send-email`
+
+Usage:
+
+```bash
+outlook-cli email send --to <emails> --subject <subject> --body <body> [options]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--to` | CSV string | Yes | - | Recipient addresses. |
+| `--subject` | string | Yes | - | Email subject. |
+| `--body` | string | Yes | - | Email body. |
+| `--cc` | CSV string | No | empty | CC recipients. |
+| `--bcc` | CSV string | No | empty | BCC recipients. |
+| `--importance` | `normal` \| `high` \| `low` | No | `normal` | Message importance. |
+| `--save-to-sent-items` | boolean | No | `true` | Save sent mail in Sent Items. |
+
+### email mark-read
+
+Maps to tool: `mark-as-read`
+
+Usage:
+
+```bash
+outlook-cli email mark-read --id <email-id> [--is-read true|false]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--id` | string | Yes | - | Message ID. |
+| `--is-read` | boolean | No | `true` | True = mark read, false = mark unread. |
+
+### calendar list
+
+Maps to tool: `list-events`
+
+Usage:
+
+```bash
+outlook-cli calendar list [--count <n>]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--count` | number | No | `10` | Max events returned. |
+
+### calendar create
+
+Maps to tool: `create-event`
+
+Usage:
+
+```bash
+outlook-cli calendar create --subject <subject> --start <iso> --end <iso> [options]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--subject` | string | Yes | - | Event title. |
+| `--start` | ISO datetime string | Yes | - | Start datetime. |
+| `--end` | ISO datetime string | Yes | - | End datetime. |
+| `--timezone` | string | No | server default timezone | Timezone applied to start/end wrapper. |
+| `--attendees` | CSV string | No | empty | Recipient emails invited to event. |
+| `--body` | string | No | empty | Event body/notes. |
+
+### calendar decline
+
+Maps to tool: `decline-event`
+
+Usage:
+
+```bash
+outlook-cli calendar decline --event-id <id> [--comment <text>]
+```
+
+Options:
+
+| Option | Type | Required | Description |
+|---|---|---:|---|
+| `--event-id` | string | Yes | Event ID. |
+| `--comment` | string | No | Optional decline comment. |
+
+### calendar cancel
+
+Maps to tool: `cancel-event`
+
+Usage:
+
+```bash
+outlook-cli calendar cancel --event-id <id> [--comment <text>]
+```
+
+Options:
+
+| Option | Type | Required | Description |
+|---|---|---:|---|
+| `--event-id` | string | Yes | Event ID. |
+| `--comment` | string | No | Optional cancel comment. |
+
+### calendar delete
+
+Maps to tool: `delete-event`
+
+Usage:
+
+```bash
+outlook-cli calendar delete --event-id <id>
+```
+
+Options:
+
+| Option | Type | Required | Description |
+|---|---|---:|---|
+| `--event-id` | string | Yes | Event ID. |
+
+### folder list
+
+Maps to tool: `list-folders`
+
+Usage:
+
+```bash
+outlook-cli folder list [options]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--include-item-counts` | boolean | No | `false` | Include total and unread counts. |
+| `--include-children` | boolean | No | `false` | Include child folders. |
+
+### folder create
+
+Maps to tool: `create-folder`
+
+Usage:
+
+```bash
+outlook-cli folder create --name <folder-name> [--parent-folder <name>]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--name` | string | Yes | - | New folder name. |
+| `--parent-folder` | string | No | root | Parent folder name. |
+
+### folder move
+
+Maps to tool: `move-emails`
+
+Usage:
+
+```bash
+outlook-cli folder move --email-ids <id1,id2> --target-folder <name> [--source-folder <name>]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--email-ids` | CSV string | Yes | - | Message IDs to move. |
+| `--target-folder` | string | Yes | - | Destination folder name. |
+| `--source-folder` | string | No | inbox | Optional source folder hint. |
+
+### rule list
+
+Maps to tool: `list-rules`
+
+Usage:
+
+```bash
+outlook-cli rule list [--include-details true|false]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--include-details` | boolean | No | `false` | Include full conditions/actions. |
+
+### rule create
+
+Maps to tool: `create-rule`
+
+Usage:
+
+```bash
+outlook-cli rule create --name <name> [options]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--name` | string | Yes | - | Rule display name. |
+| `--from-addresses` | CSV string | No | empty | Match sender addresses. |
+| `--contains-subject` | string | No | empty | Match subject text. |
+| `--has-attachments` | boolean | No | unset | Match emails with attachments. |
+| `--move-to-folder` | string | No | unset | Move matching email to folder. |
+| `--mark-as-read` | boolean | No | unset | Mark matching email as read. |
+| `--is-enabled` | boolean | No | `true` | Enable rule after creation. |
+| `--sequence` | number | No | auto-generated | Execution order (lower runs first). |
+
+Validation rules:
+
+- at least one condition is required: `from-addresses`, `contains-subject`, or `has-attachments=true`
+- at least one action is required: `move-to-folder` or `mark-as-read=true`
+- sequence must be a positive integer
+
+### rule sequence
+
+Maps to tool: `edit-rule-sequence`
+
+Usage:
+
+```bash
+outlook-cli rule sequence --rule-name <name> --sequence <number>
+```
+
+Options:
+
+| Option | Type | Required | Description |
+|---|---|---:|---|
+| `--rule-name` | string | Yes | Existing rule display name. |
+| `--sequence` | number | Yes | New rule order (positive integer). |
+
+### doctor
+
+Usage:
+
+```bash
+outlook-cli doctor
+```
+
+Reports:
+
+- runtime details (`node`, platform, cwd)
+- auth configuration presence
+- token file path and existence
+- auth server reachability
+- warnings list
+
+### update
+
+Usage:
+
+```bash
+outlook-cli update [--to latest|x.y.z] [--run]
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--to` | string | No | `latest` | Version target for global npm install. |
+| `--run` | boolean | No | `false` | Executes global update immediately. |
+
+When `--run` is not provided, command prints the exact update command only.
+
+## MCP tool reference
+
+This section documents all tools returned by `outlook-cli tools list`.
+
+### about
+
+Description: Returns package/server summary.
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| none | - | - | No input fields. |
+
+### authenticate
+
+Description: Returns auth URL guidance or creates test token in test mode.
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `force` | boolean | No | Force re-authentication. |
+
+### check-auth-status
+
+Description: Checks if a valid access token is available.
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| none | - | - | No input fields. |
+
+### list-events
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `count` | number | No | Number of events to fetch (default 10, max 50). |
+
+### decline-event
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `eventId` | string | Yes | Event ID to decline. |
+| `comment` | string | No | Optional decline comment. |
+
+### create-event
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `subject` | string | Yes | Event subject/title. |
+| `start` | string or object | Yes | Start datetime ISO string, or `{ dateTime, timeZone }`. |
+| `end` | string or object | Yes | End datetime ISO string, or `{ dateTime, timeZone }`. |
+| `attendees` | string[] | No | Attendee email addresses. |
+| `body` | string | No | Event body content. |
+
+### cancel-event
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `eventId` | string | Yes | Event ID to cancel. |
+| `comment` | string | No | Optional cancellation comment. |
+
+### delete-event
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `eventId` | string | Yes | Event ID to delete. |
+
+### list-emails
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `folder` | string | No | Folder name, default inbox. |
+| `count` | number | No | Number of emails to fetch (default 10, max 50). |
+
+### search-emails
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `query` | string | No | Full-text query. |
+| `folder` | string | No | Folder to search in. |
+| `from` | string | No | Sender filter. |
+| `to` | string | No | Recipient filter. |
+| `subject` | string | No | Subject filter. |
+| `hasAttachments` | boolean | No | Restrict to messages with attachments. |
+| `unreadOnly` | boolean | No | Restrict to unread messages. |
+| `count` | number | No | Result count limit. |
+
+### read-email
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `id` | string | Yes | Message ID. |
+
+### send-email
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `to` | string | Yes | Comma-separated recipient list. |
+| `cc` | string | No | Comma-separated CC recipients. |
+| `bcc` | string | No | Comma-separated BCC recipients. |
+| `subject` | string | Yes | Email subject. |
+| `body` | string | Yes | Email body, text or HTML. |
+| `importance` | string | No | `normal`, `high`, or `low`. |
+| `saveToSentItems` | boolean | No | Save message in sent folder. |
+
+### mark-as-read
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `id` | string | Yes | Message ID. |
+| `isRead` | boolean | No | Read state. Default true. |
+
+### list-folders
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `includeItemCounts` | boolean | No | Include item counts. |
+| `includeChildren` | boolean | No | Include child folders. |
+
+### create-folder
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `name` | string | Yes | Folder name to create. |
+| `parentFolder` | string | No | Parent folder name. |
+
+### move-emails
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `emailIds` | string | Yes | Comma-separated message IDs. |
+| `targetFolder` | string | Yes | Destination folder name. |
+| `sourceFolder` | string | No | Source folder name (hint). |
+
+### list-rules
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `includeDetails` | boolean | No | Include full conditions/actions. |
+
+### create-rule
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `name` | string | Yes | Rule name. |
+| `fromAddresses` | string | No | Comma-separated sender addresses. |
+| `containsSubject` | string | No | Subject text condition. |
+| `hasAttachments` | boolean | No | Attachment condition. |
+| `moveToFolder` | string | No | Action: move to folder. |
+| `markAsRead` | boolean | No | Action: mark as read. |
+| `isEnabled` | boolean | No | Enabled state (default true). |
+| `sequence` | number | No | Execution order. Lower runs first. |
+
+### edit-rule-sequence
+
+| Field | Type | Required | Description |
+|---|---|---:|---|
+| `ruleName` | string | Yes | Existing rule name. |
+| `sequence` | number | Yes | New execution order. |
+
+## Environment variables
+
+### Required for real Microsoft Graph auth
+
+- `OUTLOOK_CLIENT_ID`
+- `OUTLOOK_CLIENT_SECRET`
+
+Backward-compatible aliases:
+
+- `MS_CLIENT_ID`
+- `MS_CLIENT_SECRET`
+
+### Optional
+
+- `OUTLOOK_SCOPES` or `MS_SCOPES`
+- `OUTLOOK_AUTH_SERVER_URL` or `MS_AUTH_SERVER_URL`
+- `OUTLOOK_REDIRECT_URI` or `MS_REDIRECT_URI`
+- `OUTLOOK_TOKEN_STORE_PATH` or `MS_TOKEN_STORE_PATH`
+- `OUTLOOK_TOKEN_ENDPOINT` or `MS_TOKEN_ENDPOINT`
+- `USE_TEST_MODE=true`
+- `OUTLOOK_DEBUG=true` or `MCP_DEBUG=true`