Diagnostics

When something isn't working — a failed login, a model that won't load, an MCP server that won't connect — cluster doctor gathers everything relevant in one pass, instead of running cluster whoami, cluster config show, cluster models, and cluster mcp by hand and stitching the results together.

cluster doctor

It prints a grouped report of read-only checks across your system, runtime, terminal, config.toml, stored auth, local state, update status, git, required tools, MCP servers, gateway connectivity, and available models. Each check reports a status — ok, warn, or fail — with supporting details and, where relevant, a suggested fix.

doctor is read-only and one-shot: it never refreshes your auth, writes config, starts MCP servers, or opens the interactive UI. Network and git probes use short timeouts.

Output

By default the report groups checks by category for reading in your terminal:

Cluster Doctor: ok (11 checks, 0 failed, 0 warnings)
Generated: 2024-01-01T00:00:00Z    cluster 0.1.0

system
  [ok] cluster.system - macos / aarch64 (0 ms)
      os: macos
      arch: aarch64
...

Flags

Sharing a report safely

doctor redacts secrets before printing or serializing: auth tokens, request headers, credentials embedded in URLs, secret-like environment values, and the contents of your credential file are never included. The --json output is a stable, redacted report you can attach to a support request:

cluster doctor --json > cluster-doctor.json

Exit code

doctor exits non-zero only on a true failure — a config.toml that won't parse, an unreadable or malformed auth.json, or a 401 from the gateway. Warnings (for example a missing config.toml or no stored login) do not make it exit non-zero, so it's safe to run early in a script.

Next steps

• Models & configuration — settings in config.toml, plus MCP servers and custom skills.
• Exec & sessions — run prompts non-interactively and manage saved sessions.