outlook-cli 1.2.1 → 1.2.2

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,9 +36,20 @@ 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
@@ -86,4 +99,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,7 +10,7 @@ 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
+- Human-friendly commands with rich terminal output, theme presets, and machine-friendly `--json`/`--ai` mode
 - 19 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
 ```
 
 ---
@@ -750,6 +761,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 +813,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
 ```
 

package/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * Production-oriented local CLI for outlook-cli.
  *
@@ -22,10 +22,51 @@ const { listTools, getTool, invokeTool } = require('./tool-registry');
 
 const CLI_BIN_NAME = 'outlook-cli';
 const SPINNER_FRAMES = ['|', '/', '-', '\\'];
+const THEMES = Object.freeze({
+  k9s: {
+    title: ['bold', 'cyanBright'],
+    section: ['bold', 'greenBright'],
+    ok: ['bold', 'greenBright'],
+    warn: ['bold', 'yellowBright'],
+    err: ['bold', 'redBright'],
+    muted: ['gray'],
+    accent: ['bold', 'cyan'],
+    key: ['bold', 'whiteBright'],
+    value: ['cyan'],
+    border: ['cyanBright']
+  },
+  ocean: {
+    title: ['bold', 'blueBright'],
+    section: ['bold', 'cyanBright'],
+    ok: ['bold', 'green'],
+    warn: ['bold', 'yellow'],
+    err: ['bold', 'redBright'],
+    muted: ['gray'],
+    accent: ['bold', 'magentaBright'],
+    key: ['bold', 'white'],
+    value: ['blueBright'],
+    border: ['blue']
+  },
+  mono: {
+    title: ['bold', 'white'],
+    section: ['bold', 'white'],
+    ok: ['bold', 'white'],
+    warn: ['bold', 'white'],
+    err: ['bold', 'white'],
+    muted: ['gray'],
+    accent: ['bold', 'white'],
+    key: ['bold', 'white'],
+    value: ['white'],
+    border: ['gray']
+  }
+});
+const DEFAULT_THEME_NAME = 'k9s';
 const UI_STATE = {
   plain: false,
   color: false,
-  animate: false
+  animate: false,
+  themeName: DEFAULT_THEME_NAME,
+  theme: THEMES[DEFAULT_THEME_NAME]
 };
 
 function cliCommand(pathTail = '') {
@@ -207,42 +248,75 @@ function asCsv(value) {
 }
 
 function setUiState(options, outputMode) {
+  const aiMode = asBoolean(readOption(options, 'ai', false), false);
   const plain = asBoolean(readOption(options, 'plain', false), false);
   const colorOption = readOption(options, 'color');
   const animateOption = readOption(options, 'animate');
+  const requestedTheme = String(readOption(
+    options,
+    'theme',
+    process.env.OUTLOOK_CLI_THEME || DEFAULT_THEME_NAME
+  )).trim().toLowerCase();
+  const themeName = THEMES[requestedTheme] ? requestedTheme : DEFAULT_THEME_NAME;
   const isTextMode = outputMode === 'text';
   const isInteractive = isTextMode && process.stdout.isTTY;
 
-  UI_STATE.plain = plain;
-  UI_STATE.color = isInteractive && !plain && colorOption !== false;
-  UI_STATE.animate = isInteractive && !plain && animateOption !== false;
+  UI_STATE.plain = plain || aiMode;
+  UI_STATE.color = isInteractive && !UI_STATE.plain && colorOption !== false;
+  UI_STATE.animate = isInteractive && !UI_STATE.plain && animateOption !== false;
+  UI_STATE.themeName = themeName;
+  UI_STATE.theme = THEMES[themeName];
 
   chalk.level = UI_STATE.color ? Math.max(chalk.level, 1) : 0;
 }
 
-function tone(text, kind) {
-  if (!UI_STATE.color) {
+function applyThemeStyle(text, stylePath) {
+  if (!UI_STATE.color || !stylePath) {
     return text;
   }
 
-  switch (kind) {
-    case 'title':
-      return chalk.bold.cyan(text);
-    case 'section':
-      return chalk.bold.blue(text);
-    case 'ok':
-      return chalk.green(text);
-    case 'warn':
-      return chalk.yellow(text);
-    case 'err':
-      return chalk.red(text);
-    case 'muted':
-      return chalk.gray(text);
-    case 'accent':
-      return chalk.magenta(text);
-    default:
+  const chain = Array.isArray(stylePath) ? stylePath : [stylePath];
+  let painter = chalk;
+
+  for (const segment of chain) {
+    if (!(segment in painter)) {
       return text;
+    }
+
+    painter = painter[segment];
   }
+
+  return painter(text);
+}
+
+function terminalWidth() {
+  const raw = Number(process.stdout.columns || 100);
+  if (!Number.isFinite(raw)) {
+    return 100;
+  }
+
+  return Math.max(72, Math.min(120, raw));
+}
+
+function padRight(value, width) {
+  const text = String(value);
+  if (text.length >= width) {
+    return text;
+  }
+
+  return `${text}${' '.repeat(width - text.length)}`;
+}
+
+function separator(width = terminalWidth()) {
+  return '-'.repeat(Math.max(24, width));
+}
+
+function formatRow(left, right, leftWidth = 34) {
+  return `  ${tone(padRight(left, leftWidth), 'key')} ${tone(right, 'muted')}`;
+}
+
+function tone(text, kind) {
+  return applyThemeStyle(text, UI_STATE.theme[kind]);
 }
 
 function badge(kind) {
@@ -317,9 +391,242 @@ function formatResultText(result) {
   return JSON.stringify(result, null, 2);
 }
 
+function normalizeLineEndings(value) {
+  return String(value || '').replace(/\r\n/g, '\n').trim();
+}
+
+function extractTextChunksFromResult(result) {
+  if (!result || !Array.isArray(result.content)) {
+    return [];
+  }
+
+  return result.content
+    .filter((entry) => entry && entry.type === 'text' && typeof entry.text === 'string')
+    .map((entry) => normalizeLineEndings(entry.text))
+    .filter(Boolean);
+}
+
+function firstNonEmptyLine(text) {
+  const line = normalizeLineEndings(text)
+    .split('\n')
+    .map((entry) => entry.trim())
+    .find(Boolean);
+
+  return line || '';
+}
+
+function parseNumberedBlocks(text) {
+  const normalized = normalizeLineEndings(text);
+  const matches = normalized.match(/\d+\.\s[\s\S]*?(?=(?:\n\d+\.\s)|$)/g);
+  if (!matches) {
+    return [];
+  }
+
+  return matches.map((entry) => entry.trim()).filter(Boolean);
+}
+
+function parseEmailListFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  const body = normalized.replace(/^Found[^\n]*:\n\n?/i, '');
+  const blocks = parseNumberedBlocks(body);
+
+  return blocks.map((block) => {
+    const lines = block.split('\n').map((line) => line.trim()).filter(Boolean);
+    const headline = lines[0] || '';
+    const subjectLine = lines.find((line) => line.startsWith('Subject:')) || '';
+    const idLine = lines.find((line) => line.startsWith('ID:')) || '';
+    const match = headline.match(/^(\d+)\.\s(?:\[UNREAD\]\s)?(.+?)\s-\sFrom:\s(.+?)\s\((.+)\)$/);
+
+    return {
+      index: match ? Number(match[1]) : null,
+      unread: headline.includes('[UNREAD]'),
+      receivedAt: match ? match[2] : null,
+      from: match ? { name: match[3], email: match[4] } : null,
+      subject: subjectLine ? subjectLine.replace(/^Subject:\s*/, '') : null,
+      id: idLine ? idLine.replace(/^ID:\s*/, '') : null,
+      raw: block
+    };
+  });
+}
+
+function parseEventListFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  const body = normalized.replace(/^Found[^\n]*:\n\n?/i, '');
+  const blocks = parseNumberedBlocks(body);
+
+  return blocks.map((block) => {
+    const lines = block.split('\n').map((line) => line.trim()).filter(Boolean);
+    const headline = lines[0] || '';
+    const startLine = lines.find((line) => line.startsWith('Start:')) || '';
+    const endLine = lines.find((line) => line.startsWith('End:')) || '';
+    const summaryLine = lines.find((line) => line.startsWith('Summary:')) || '';
+    const idLine = lines.find((line) => line.startsWith('ID:')) || '';
+    const match = headline.match(/^(\d+)\.\s(.+?)\s-\sLocation:\s(.+)$/);
+
+    return {
+      index: match ? Number(match[1]) : null,
+      subject: match ? match[2] : null,
+      location: match ? match[3] : null,
+      start: startLine ? startLine.replace(/^Start:\s*/, '') : null,
+      end: endLine ? endLine.replace(/^End:\s*/, '') : null,
+      summary: summaryLine ? summaryLine.replace(/^Summary:\s*/, '') : null,
+      id: idLine ? idLine.replace(/^ID:\s*/, '') : null,
+      raw: block
+    };
+  });
+}
+
+function parseFolderListFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  if (normalized.startsWith('Folder Hierarchy:')) {
+    const lines = normalized
+      .replace(/^Folder Hierarchy:\n\n?/i, '')
+      .split('\n')
+      .filter(Boolean);
+
+    return lines.map((line) => {
+      const leadingSpaces = line.match(/^\s*/);
+      const level = leadingSpaces ? Math.floor(leadingSpaces[0].length / 2) : 0;
+      return {
+        level,
+        name: line.trim(),
+        raw: line
+      };
+    });
+  }
+
+  const body = normalized.replace(/^Found[^\n]*:\n\n?/i, '');
+  return body
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line, index) => ({
+      index: index + 1,
+      name: line,
+      raw: line
+    }));
+}
+
+function parseRuleListFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  const body = normalized.replace(/^Found[^\n]*:\n\n?/i, '');
+  const blocks = parseNumberedBlocks(body);
+
+  return blocks.map((block) => {
+    const lines = block.split('\n').map((line) => line.trim()).filter(Boolean);
+    const headline = lines[0] || '';
+    const conditionsLine = lines.find((line) => line.startsWith('Conditions:')) || '';
+    const actionsLine = lines.find((line) => line.startsWith('Actions:')) || '';
+    const match = headline.match(/^(\d+)\.\s(.+?)(?:\s-\sSequence:\s(.+))?$/);
+
+    return {
+      index: match ? Number(match[1]) : null,
+      name: match ? match[2] : null,
+      sequence: match && match[3] ? match[3] : null,
+      conditions: conditionsLine ? conditionsLine.replace(/^Conditions:\s*/, '') : null,
+      actions: actionsLine ? actionsLine.replace(/^Actions:\s*/, '') : null,
+      raw: block
+    };
+  });
+}
+
+function parseReadEmailFromText(text) {
+  const normalized = normalizeLineEndings(text);
+  const sections = normalized.split(/\n\n+/);
+  const headerSection = sections.shift() || '';
+  const headerLines = headerSection.split('\n').map((line) => line.trim()).filter(Boolean);
+  const headers = {};
+
+  headerLines.forEach((line) => {
+    const index = line.indexOf(':');
+    if (index > 0) {
+      const key = line.slice(0, index).trim();
+      const value = line.slice(index + 1).trim();
+      headers[key] = value;
+    }
+  });
+
+  return {
+    headers,
+    body: sections.join('\n\n').trim(),
+    raw: normalized
+  };
+}
+
+function normalizeToolResult(toolName, args, result) {
+  const textChunks = extractTextChunksFromResult(result);
+  const text = textChunks.join('\n\n');
+  const normalized = {
+    tool: toolName,
+    args: args || {},
+    summary: firstNonEmptyLine(text),
+    textChunks
+  };
+
+  switch (toolName) {
+    case 'list-emails':
+    case 'search-emails':
+      normalized.kind = 'email-list';
+      normalized.items = parseEmailListFromText(text);
+      normalized.count = normalized.items.length;
+      return normalized;
+
+    case 'list-events':
+      normalized.kind = 'event-list';
+      normalized.items = parseEventListFromText(text);
+      normalized.count = normalized.items.length;
+      return normalized;
+
+    case 'list-folders':
+      normalized.kind = 'folder-list';
+      normalized.items = parseFolderListFromText(text);
+      normalized.count = normalized.items.length;
+      return normalized;
+
+    case 'list-rules':
+      normalized.kind = 'rule-list';
+      normalized.items = parseRuleListFromText(text);
+      normalized.count = normalized.items.length;
+      return normalized;
+
+    case 'read-email':
+      normalized.kind = 'email-detail';
+      normalized.record = parseReadEmailFromText(text);
+      return normalized;
+
+    default:
+      normalized.kind = 'text';
+      normalized.lines = normalizeLineEndings(text).split('\n').filter(Boolean);
+      return normalized;
+  }
+}
+
+function buildStructuredPayload(payload) {
+  const response = { ...payload };
+
+  if (payload.tool && payload.result) {
+    response.structured = normalizeToolResult(payload.tool, payload.args, payload.result);
+    return response;
+  }
+
+  response.structured = {
+    command: payload.command || null,
+    summary: typeof payload.message === 'string' ? payload.message : null,
+    data: payload.data || null
+  };
+
+  return response;
+}
+
+function printTextBlock(title, body) {
+  process.stdout.write(`${tone(title, 'section')}\n`);
+  process.stdout.write(`${tone(separator(32), 'border')}\n`);
+  process.stdout.write(`${body}\n`);
+}
+
 function printSuccess(outputMode, payload) {
   if (outputMode === 'json') {
-    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify(buildStructuredPayload(payload), null, 2)}\n`);
     return;
   }
 
@@ -328,11 +635,11 @@ function printSuccess(outputMode, payload) {
   }
 
   if (payload.result) {
-    process.stdout.write(`${tone('Result:', 'section')}\n${formatResultText(payload.result)}\n`);
+    printTextBlock('Result', formatResultText(payload.result));
   }
 
   if (payload.data && !payload.result) {
-    process.stdout.write(`${tone('Details:', 'section')}\n${JSON.stringify(payload.data, null, 2)}\n`);
+    printTextBlock('Details', JSON.stringify(payload.data, null, 2));
   }
 }
 
@@ -351,11 +658,16 @@ function printError(outputMode, error) {
 
   process.stderr.write(`${badge('err')} ${error.message}\n`);
   if (error instanceof UsageError) {
-    process.stderr.write(`${tone(`Run '${cliCommand('help')}' to see valid usage.`, 'muted')}\n`);
+    process.stderr.write(`${tone(separator(42), 'border')}\n`);
+    process.stderr.write(`${tone(formatRow('help', `Run '${cliCommand('help')}' to see valid usage.`, 14), 'muted')}\n`);
   }
 }
 
 function buildOutputMode(options) {
+  if (asBoolean(readOption(options, 'ai', false), false)) {
+    return 'json';
+  }
+
   const outputOption = readOption(options, 'output');
   if (outputOption === 'json') {
     return 'json';
@@ -422,43 +734,49 @@ async function callTool(toolName, args, outputMode, commandLabel) {
 function printUsage() {
   const usage = [
     `${tone(CLI_BIN_NAME, 'title')} ${tone(`v${pkg.version}`, 'muted')}`,
+    tone(`Theme: ${UI_STATE.themeName} | AI mode: --ai`, 'muted'),
+    tone(separator(), 'border'),
     '',
-    tone('Global install:', 'section'),
-    `  npm i -g ${pkg.name}`,
+    tone('Install', 'section'),
+    formatRow('global', `npm i -g ${pkg.name}`, 18),
+    formatRow('local', 'npm install', 18),
     '',
-    tone('Usage:', 'section'),
-    `  ${cliCommand('<command> [subcommand] [options]')}`,
+    tone('Usage', 'section'),
+    `  ${tone(cliCommand('<command> [subcommand] [options]'), 'accent')}`,
     '',
-    tone('Global options:', 'section'),
-    '  --json                 Output machine-readable JSON',
-    '  --output text|json     Explicit output mode',
-    '  --plain                Disable rich colors and animations',
-    '  --no-color             Disable colors explicitly',
-    '  --no-animate           Disable spinner animations',
-    '  --help                 Show help',
-    '  --version              Show version',
+    tone('Global options', 'section'),
+    formatRow('--json', 'Machine-readable JSON output'),
+    formatRow('--ai', 'Agent-safe alias for JSON mode (no spinners/colors)'),
+    formatRow('--output text|json', 'Explicit output mode'),
+    formatRow('--theme k9s|ocean|mono', 'Theme preset for text output'),
+    formatRow('--plain', 'Disable rich styling and animations'),
+    formatRow('--no-color', 'Disable colors explicitly'),
+    formatRow('--no-animate', 'Disable spinner animations'),
+    formatRow('--help', 'Show help'),
+    formatRow('--version', 'Show version'),
     '',
-    tone('Core commands:', 'section'),
-    '  commands               Show all command groups and tools',
-    '  tools list',
-    '  tools schema <tool-name>',
-    '  call <tool-name> [--args-json "{...}"] [--arg key=value]',
-    '  auth status|url|login|logout|server',
-    '    auth login [--client-id <id>] [--client-secret <secret>] [--prompt-credentials true|false]',
-    '    auth server [--status] [--start]',
-    '  update [--run] [--to latest|x.y.z]',
-    '  doctor',
+    tone('Core commands', 'section'),
+    formatRow('commands', 'Show command groups and available tools'),
+    formatRow('tools list', 'List all tool names and descriptions'),
+    formatRow('tools schema <tool-name>', 'Show JSON schema for one tool'),
+    formatRow('call <tool-name> [--args-json] [--arg]', 'Invoke any tool directly'),
+    formatRow('auth status|url|login|logout|server', 'Authentication and OAuth server control'),
+    formatRow('agents guide', 'AI agent quick-start and orchestration tips'),
+    formatRow('doctor', 'Run diagnostics and environment checks'),
+    formatRow('update [--run] [--to latest|x.y.z]', 'Check or apply global update'),
+    formatRow('mcp-server', 'Run stdio MCP server (for Claude/Codex/VS Code)'),
     '',
-    tone('Human-friendly command groups:', 'section'),
-    '  email list|search|read|send|mark-read',
-    '  calendar list|create|decline|cancel|delete',
-    '  folder list|create|move',
-    '  rule list|create|sequence',
+    tone('Command groups', 'section'),
+    formatRow('email', 'list|search|read|send|mark-read'),
+    formatRow('calendar', 'list|create|decline|cancel|delete'),
+    formatRow('folder', 'list|create|move'),
+    formatRow('rule', 'list|create|sequence'),
     '',
-    tone('Examples:', 'section'),
+    tone('Examples', 'section'),
     `  ${cliCommand('auth login --open --start-server --wait --timeout 180')}`,
-    `  ${cliCommand('email list --folder inbox --count 15')}`,
-    `  ${cliCommand('call search-emails --arg query=invoice --arg unreadOnly=true --json')}`,
+    `  ${cliCommand('auth login --open --client-id <id> --client-secret <secret>')}`,
+    `  ${cliCommand('agents guide --json')}`,
+    `  ${cliCommand("call list-emails --args-json '{\"folder\":\"inbox\",\"count\":5}' --ai")}`,
     `  ${cliCommand('tools schema send-email')}`,
     `  ${cliCommand('update --run')}`
   ];
@@ -553,9 +871,10 @@ function buildCommandCatalog() {
       calendar: ['list', 'create', 'decline', 'cancel', 'delete'],
       folder: ['list', 'create', 'move'],
       rule: ['list', 'create', 'sequence'],
+      agents: ['guide'],
       tools: ['list', 'schema'],
       generic: ['call'],
-      system: ['doctor', 'update', 'version', 'help']
+      system: ['doctor', 'update', 'version', 'help', 'mcp-server']
     },
     tools: toolCatalog
   };
@@ -570,18 +889,21 @@ function printCommandCatalog(outputMode) {
     data: catalog,
     message: outputMode === 'text'
       ? [
-        `Command groups:`,
-        `- auth: ${catalog.commandGroups.auth.join(', ')}`,
-        `- email: ${catalog.commandGroups.email.join(', ')}`,
-        `- calendar: ${catalog.commandGroups.calendar.join(', ')}`,
-        `- folder: ${catalog.commandGroups.folder.join(', ')}`,
-        `- rule: ${catalog.commandGroups.rule.join(', ')}`,
-        `- tools: ${catalog.commandGroups.tools.join(', ')}`,
-        `- generic: ${catalog.commandGroups.generic.join(', ')}`,
-        `- system: ${catalog.commandGroups.system.join(', ')}`,
+        tone('Command groups', 'section'),
+        tone(separator(48), 'border'),
+        formatRow('auth', catalog.commandGroups.auth.join(', '), 14),
+        formatRow('email', catalog.commandGroups.email.join(', '), 14),
+        formatRow('calendar', catalog.commandGroups.calendar.join(', '), 14),
+        formatRow('folder', catalog.commandGroups.folder.join(', '), 14),
+        formatRow('rule', catalog.commandGroups.rule.join(', '), 14),
+        formatRow('agents', catalog.commandGroups.agents.join(', '), 14),
+        formatRow('tools', catalog.commandGroups.tools.join(', '), 14),
+        formatRow('generic', catalog.commandGroups.generic.join(', '), 14),
+        formatRow('system', catalog.commandGroups.system.join(', '), 14),
         '',
-        `Available MCP tools (${catalog.tools.length}):`,
-        ...catalog.tools.map((tool) => `- ${tool.name}`)
+        tone(`Available MCP tools (${catalog.tools.length})`, 'section'),
+        tone(separator(48), 'border'),
+        ...catalog.tools.map((tool) => formatRow(tool.name, tool.description || 'No description', 28))
       ].join('\n')
       : undefined
   });
@@ -1290,6 +1612,56 @@ async function handleRuleCommand(action, options, outputMode) {
   }
 }
 
+function startMcpServerProcess() {
+  // eslint-disable-next-line global-require
+  require('./index');
+}
+
+async function handleAgentsCommand(action, outputMode) {
+  const subcommand = action || 'guide';
+  if (subcommand !== 'guide') {
+    throw new UsageError('Unknown agents command. Use: agents guide');
+  }
+
+  const tools = listTools();
+  const guide = {
+    totalTools: tools.length,
+    toolNames: tools.map((tool) => tool.name),
+    mcpServerCommand: `${CLI_BIN_NAME} mcp-server`,
+    recommendedFlow: [
+      `${CLI_BIN_NAME} auth status --json`,
+      `${CLI_BIN_NAME} tools list --json`,
+      `${CLI_BIN_NAME} tools schema <tool-name> --json`,
+      `${CLI_BIN_NAME} call <tool-name> --args-json '{"...":"..."}' --json`
+    ],
+    safetyNotes: [
+      'Prefer --json or --ai for agent workflows.',
+      'Use tools schema before call for strict argument validation.',
+      'Use auth status before calling Microsoft Graph tools.'
+    ]
+  };
+
+  printSuccess(outputMode, {
+    ok: true,
+    command: 'agents guide',
+    data: guide,
+    message: outputMode === 'text'
+      ? [
+        tone('Agent guide', 'section'),
+        tone(separator(48), 'border'),
+        formatRow('mcp server', guide.mcpServerCommand, 18),
+        formatRow('available tools', String(guide.totalTools), 18),
+        '',
+        tone('Recommended workflow', 'section'),
+        ...guide.recommendedFlow.map((line) => `  ${tone(line, 'accent')}`),
+        '',
+        tone('Best practices', 'section'),
+        ...guide.safetyNotes.map((note) => formatRow('note', note, 18))
+      ].join('\n')
+      : undefined
+  });
+}
+
 async function handleDoctorCommand(outputMode) {
   const tokenPath = config.AUTH_CONFIG.tokenStorePath;
   const tokenExists = fs.existsSync(tokenPath);
@@ -1445,6 +1817,11 @@ async function run() {
       await handleGenericCall(positional.slice(1), options, outputMode);
       return;
 
+    case 'agents':
+    case 'agent':
+      await handleAgentsCommand(action, outputMode);
+      return;
+
     case 'auth':
       await handleAuthCommand(action, options, outputMode);
       return;
@@ -1473,6 +1850,10 @@ async function run() {
       await handleUpdateCommand(options, outputMode);
       return;
 
+    case 'mcp-server':
+      startMcpServerProcess();
+      return;
+
     default:
       throw new UsageError(`Unknown command: ${command}. Run '${cliCommand('help')}' for usage.`);
   }

package/docs/REFERENCE.md

@@ -11,7 +11,8 @@ This document is the complete, publish-ready reference for:
 - CLI binary: `outlook-cli`
 - Output mode:
   - `text` (default)
-  - `json` (with `--json` or `--output json`)
+  - `json` (with `--json`, `--ai`, or `--output json`)
+- JSON responses include `structured` for normalized, machine-friendly fields while preserving raw `result`.
 - Option key normalization:
   - `--event-id` and `--eventId` map to the same internal key.
   - `--start-server` and `--startServer` are equivalent.
@@ -24,7 +25,9 @@ This document is the complete, publish-ready reference for:
 | Option | Type | Required | Default | Description |
 |---|---|---:|---|---|
 | `--json` | boolean | No | `false` | Forces JSON output for automation and agents. |
+| `--ai` | boolean | No | `false` | Alias for JSON-first agent mode (no rich UI noise). |
 | `--output` | `text` \| `json` | No | `text` | Explicit output mode override. |
+| `--theme` | `k9s` \| `ocean` \| `mono` | No | `k9s` | Text-mode color theme preset. |
 | `--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. |
@@ -40,11 +43,13 @@ This document is the complete, publish-ready reference for:
 | `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. |
+| `agents guide` | Prints AI-agent workflow guidance and best practices. |
 | `auth ...` | Authentication command group. |
 | `email ...` | Email command group. |
 | `calendar ...` | Calendar command group. |
 | `folder ...` | Folder command group. |
 | `rule ...` | Rules command group. |
+| `mcp-server` | Starts the stdio MCP server (same behavior as `node index.js`). |
 | `doctor` | Environment and auth diagnostics. |
 | `update` | Prints or runs global npm update command. |
 | `help` | Same as `--help`. |
@@ -118,6 +123,18 @@ Examples:
 ```bash
 outlook-cli call list-emails --args-json '{"count":5}'
 outlook-cli call search-emails --arg query=invoice --arg unreadOnly=true --json
+outlook-cli call send-email --args-json '{"to":"a@example.com","subject":"Hi","body":"Hello"}' --ai
+```
+
+### agents guide
+
+Prints AI-agent command patterns and orchestration best practices.
+
+Usage:
+
+```bash
+outlook-cli agents guide
+outlook-cli agents guide --json
 ```
 
 ### auth status
@@ -137,7 +154,7 @@ Prints the Microsoft OAuth URL generated from current config.
 Usage:
 
 ```bash
-outlook-cli auth url
+outlook-cli auth url [--client-id <id>]
 ```
 
 ### auth login
@@ -159,6 +176,27 @@ Options:
 | `--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. |
+| `--client-id` | string | No | env/config | Runtime override for client ID. |
+| `--client-secret` | string | No | env/config | Runtime override for client secret value. |
+| `--prompt-credentials` | boolean | No | `true` | Prompt for missing credentials in interactive terminals. |
+
+### auth server
+
+Checks or starts the local OAuth callback server.
+
+Usage:
+
+```bash
+outlook-cli auth server --status
+outlook-cli auth server --start
+```
+
+Options:
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `--status` | boolean | No | `true` when `--start` is not passed | Prints reachability status only. |
+| `--start` | boolean | No | `false` | Starts callback server in background if not running. |
 
 ### auth logout
 

package/email/search.js

@@ -6,6 +6,12 @@ const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolderPath } = require('./folder-utils');
 
+function debugLog(...args) {
+  if (config.DEBUG_LOGS) {
+    console.error(...args);
+  }
+}
+
 /**
  * Search emails handler
  * @param {object} args - Tool arguments
@@ -27,7 +33,7 @@ async function handleSearchEmails(args) {
     
     // Resolve the folder path
     const endpoint = await resolveFolderPath(accessToken, folder);
-    console.error(`Using endpoint: ${endpoint} for folder: ${folder}`);
+    debugLog(`Using endpoint: ${endpoint} for folder: ${folder}`);
     
     // Execute progressive search
     const response = await progressiveSearch(
@@ -76,16 +82,16 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
   // 1. Try combined search (most specific)
   try {
     const params = buildSearchParams(searchTerms, filterTerms, count);
-    console.error("Attempting combined search with params:", params);
+    debugLog('Attempting combined search with params:', params);
     searchAttempts.push("combined-search");
     
     const response = await callGraphAPI(accessToken, 'GET', endpoint, null, params);
     if (response.value && response.value.length > 0) {
-      console.error(`Combined search successful: found ${response.value.length} results`);
+      debugLog(`Combined search successful: found ${response.value.length} results`);
       return response;
     }
   } catch (error) {
-    console.error(`Combined search failed: ${error.message}`);
+    debugLog(`Combined search failed: ${error.message}`);
   }
   
   // 2. Try each search term individually, starting with most specific
@@ -94,7 +100,7 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
   for (const term of searchPriority) {
     if (searchTerms[term]) {
       try {
-        console.error(`Attempting search with only ${term}: "${searchTerms[term]}"`);
+        debugLog(`Attempting search with only ${term}: "${searchTerms[term]}"`);
         searchAttempts.push(`single-term-${term}`);
         
         // For single term search, only use $search with that term
@@ -118,11 +124,11 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
         
         const response = await callGraphAPI(accessToken, 'GET', endpoint, null, simplifiedParams);
         if (response.value && response.value.length > 0) {
-          console.error(`Search with ${term} successful: found ${response.value.length} results`);
+          debugLog(`Search with ${term} successful: found ${response.value.length} results`);
           return response;
         }
       } catch (error) {
-        console.error(`Search with ${term} failed: ${error.message}`);
+        debugLog(`Search with ${term} failed: ${error.message}`);
       }
     }
   }
@@ -130,7 +136,7 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
   // 3. Try with only boolean filters
   if (filterTerms.hasAttachments === true || filterTerms.unreadOnly === true) {
     try {
-      console.error("Attempting search with only boolean filters");
+      debugLog('Attempting search with only boolean filters');
       searchAttempts.push("boolean-filters-only");
       
       const filterOnlyParams = {
@@ -143,15 +149,15 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
       addBooleanFilters(filterOnlyParams, filterTerms);
       
       const response = await callGraphAPI(accessToken, 'GET', endpoint, null, filterOnlyParams);
-      console.error(`Boolean filter search found ${response.value?.length || 0} results`);
+      debugLog(`Boolean filter search found ${response.value?.length || 0} results`);
       return response;
     } catch (error) {
-      console.error(`Boolean filter search failed: ${error.message}`);
+      debugLog(`Boolean filter search failed: ${error.message}`);
     }
   }
   
   // 4. Final fallback: just get recent emails
-  console.error("All search strategies failed, falling back to recent emails");
+  debugLog('All search strategies failed, falling back to recent emails');
   searchAttempts.push("recent-emails");
   
   const basicParams = {
@@ -161,7 +167,7 @@ async function progressiveSearch(endpoint, accessToken, searchTerms, filterTerms
   };
   
   const response = await callGraphAPI(accessToken, 'GET', endpoint, null, basicParams);
-  console.error(`Fallback to recent emails found ${response.value?.length || 0} results`);
+  debugLog(`Fallback to recent emails found ${response.value?.length || 0} results`);
   
   // Add a note to the response about the search attempts
   response._searchInfo = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outlook-cli",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Production-ready Outlook CLI with optional MCP server mode powered by Microsoft Graph API",
   "keywords": [
     "outlook-cli",

package/utils/graph-api.js

@@ -5,6 +5,12 @@ const https = require('https');
 const config = require('../config');
 const mockData = require('./mock-data');
 
+function debugLog(...args) {
+  if (config.DEBUG_LOGS) {
+    console.error(...args);
+  }
+}
+
 /**
  * Makes a request to the Microsoft Graph API
  * @param {string} accessToken - The access token for authentication
@@ -17,12 +23,12 @@ const mockData = require('./mock-data');
 async function callGraphAPI(accessToken, method, path, data = null, queryParams = {}) {
   // For test tokens, we'll simulate the API call
   if (config.USE_TEST_MODE && accessToken.startsWith('test_access_token_')) {
-    console.error(`TEST MODE: Simulating ${method} ${path} API call`);
+    debugLog(`TEST MODE: Simulating ${method} ${path} API call`);
     return mockData.simulateGraphAPIResponse(method, path, data, queryParams);
   }
 
   try {
-    console.error(`Making real API call: ${method} ${path}`);
+    debugLog(`Making real API call: ${method} ${path}`);
     
     // Encode path segments properly
     const encodedPath = path.split('/')
@@ -59,11 +65,11 @@ async function callGraphAPI(accessToken, method, path, data = null, queryParams
         queryString = '?' + queryString;
       }
       
-      console.error(`Query string: ${queryString}`);
+      debugLog(`Query string: ${queryString}`);
     }
     
     const url = `${config.GRAPH_API_ENDPOINT}${encodedPath}${queryString}`;
-    console.error(`Full URL: ${url}`);
+    debugLog(`Full URL: ${url}`);
     
     return new Promise((resolve, reject) => {
       const options = {
@@ -110,7 +116,7 @@ async function callGraphAPI(accessToken, method, path, data = null, queryParams
       req.end();
     });
   } catch (error) {
-    console.error('Error calling Graph API:', error);
+    debugLog('Error calling Graph API:', error);
     throw error;
   }
 }