Skip to content

diagnostics.md

Latest commit

 

History

History
232 lines (176 loc) · 8.05 KB

diagnostics.md

File metadata and controls

232 lines (176 loc) · 8.05 KB
Raw

Diagnostics Commands

Commands for checking system health, reviewing operation history, and managing updates.

Every diagnostics command accepts global options (--account, --format, --json, --output, --verbose).

For deep technical details on the SQLite database, telemetry ring buffer, and advanced queries, see DIAGNOSTICS.md.

doctor

Run a health check that verifies your outlook-cli installation, configuration, accounts, token caches, and (optionally) connectivity to Microsoft Graph.

outlook-cli doctor
outlook-cli doctor --account work
outlook-cli doctor --offline
Option Description Default
--offline Skip network checks (token refresh, Graph API connectivity). Useful when you know you're offline and just want to verify local configuration. Run all checks

Example output (Node.js):

  outlook-cli health check
  ────────────────────────────────────────────
  ✅ Node.js version: v24.14.1
  ✅ Config directory: C:\Users\you\.outlook-cli
  ✅ Accounts configured: 2 account(s): personal, work
  ✅ [personal] Client ID: e5601814...
  ✅ [personal] Token cache: Cache file exists
  ✅ [personal] Authentication: Token acquired (silent)
  ✅ [personal] Scopes: User.Read, Mail.Read, Mail.ReadWrite, Mail.Send
  ✅ [personal] Graph API: Connected as John Smith
  ✅ Version: 2.0.0 (node)

  9 passed, 0 warnings, 0 failed

Example output (C# NativeAOT):

  outlook-cli doctor (C# / NativeAOT)
  ─────────────────────────────────────
  Runtime:           dotnet (NativeAOT)
  CLR version:       8.0.25
  OS:                Microsoft Windows NT 10.0.26602.0
  Config dir:        C:\Users\you\.outlook-cli
  Config exists:     ✓ yes
  Database:          ✓ exists
  Accounts:          2 configured
  Default account:   personal
  Token caches:      2 encrypted cache file(s)

  For detailed diagnostics, see: docs/DIAGNOSTICS.md

What Doctor Checks

Check What It Verifies Common Failure
Runtime version Node.js or .NET CLR version Unsupported runtime version
Config directory ~/.outlook-cli/ exists and is readable Directory missing (first run)
Accounts At least one account configured Run account add first
Client ID Each account has a valid client ID Missing or invalid app registration
Token cache Encrypted cache file exists Run auth login to authenticate
Authentication Token can be acquired silently (refresh works) Token expired; re-login needed
Scopes Token has required permissions App missing API permissions
Graph API Can reach graph.microsoft.com and query /me Network issues or token problems
Version Current version matches expectations Stale binary after update

When to use doctor:

  • After initial setup to verify everything is configured correctly
  • When commands fail with authentication errors
  • When you suspect network or configuration issues
  • When switching between Node.js and C# runtimes

log search

Search the operations log stored in SQLite (~/.outlook-cli/outlook-cli.db). Every CLI operation (inbox, read, search, send, etc.) is logged with timing, status, and error information.

# Show the last 50 operations (default)
outlook-cli log search

# Filter by account
outlook-cli log search --account work

# Filter by command name
outlook-cli log search --operation "mail inbox"

# Only show failures
outlook-cli log search --status failed

# Operations since a specific date
outlook-cli log search --since 2026-01-10

# Find all operations in a correlation chain
outlook-cli log search --correlation-id abc123

# Limit results
outlook-cli log search --limit 10
Option Description Default
-a, --account <alias> Filter by account alias. All accounts
-o, --operation <op> Filter by command/operation name (e.g., mail inbox, auth login). All operations
-s, --since <date> Only show operations after this date. ISO 8601 format (e.g., 2026-01-10). No date filter
--status <status> Filter by status: started, completed, or failed. All statuses
--correlation-id <id> Find all operations sharing a correlation ID. Useful for tracing a chain of related operations (e.g., a token refresh triggered by a 401 during inbox). No filter
-n, --limit <n> Maximum number of results. 50

Example output:

ID     Operation      Account    Status     Duration   Date
────────────────────────────────────────────────────────────────────────
1042   mail inbox     personal   completed  420ms      2026-01-15 09:30
1041   mail read      personal   completed  380ms      2026-01-15 09:29
1040   mail inbox     work       failed     1200ms     2026-01-15 09:28
1039   auth login     personal   completed  3500ms     2026-01-15 09:00

What Gets Logged

Every Graph API operation logs:

  • Operation name — the command that was run
  • Account — which account was used
  • Status — started, completed, or failed
  • Duration — how long the operation took
  • Correlation ID — groups related operations (e.g., a retry chain)
  • Error details — for failed operations, the error message and code

log summary

Show aggregate statistics about CLI usage over a time period.

# Default: last 7 days
outlook-cli log summary

# Last 30 days
outlook-cli log summary --days 30

# JSON output for scripting
outlook-cli log summary --json
Option Description Default
-d, --days <n> Number of days to summarize. 7
--json Output as JSON instead of text. Text

Example output (text):

  outlook-cli operations summary
  Period: last 7 day(s) (since 2026-01-08)
  ────────────────────────────────────────────
  Total operations:    142
  Errors:              3 (2.1%)
  Avg latency:         380ms
  Throttle events:     0

  By day:
    Jan 15:  28 ops
    Jan 14:  35 ops
    Jan 13:  22 ops
    ...

  Top commands:
    mail inbox:    45
    mail read:     38
    mail search:   22
    calendar today: 15

  By account:
    personal:  89 ops (1 error)
    work:      53 ops (2 errors)

upgrade

Check for updates and show instructions to upgrade outlook-cli.

outlook-cli upgrade

Node.js output:

Current version: 2.0.0 (node)
To upgrade: git pull && npm install

C# output:

Current version: 2.0.0 (dotnet/NativeAOT)
To upgrade: git pull && dotnet publish src\dotnet\OutlookCli.csproj -r win-x64 --self-contained /p:PublishAot=true -o publish\win-x64

The upgrade command does not auto-update — it shows the manual steps to rebuild from source. This is intentional: outlook-cli is source-distributed, not package-distributed, so upgrades involve pulling the latest code and rebuilding.

Telemetry

outlook-cli has an optional telemetry system (disabled by default) that collects performance and usage data locally. No data is ever sent to external services.

Enabling Telemetry

# Enable for a single command
OUTLOOK_CLI_TELEMETRY=1 outlook-cli mail inbox

# Enable permanently (add to your shell profile)
export OUTLOOK_CLI_TELEMETRY=1

What Telemetry Collects

  • In-memory ring buffer (1000 events): API call timings, error rates, retry counts. Lost when the process exits.
  • SQLite persistence (when enabled): Writes telemetry events to ~/.outlook-cli/outlook-cli.db in a telemetry table.
  • Process snapshots: Memory usage, event loop lag, active handles.

Telemetry is useful for diagnosing performance issues, identifying rate-limiting patterns, and understanding usage across accounts. See DIAGNOSTICS.md for advanced telemetry queries.