# 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.

```bash
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 [#output]

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

```text
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 [#flags]

| Flag         | Effect                                                                             |
| ------------ | ---------------------------------------------------------------------------------- |
| `--summary`  | Compact output — status rows and remedies only, without the per-check detail lines |
| `--json`     | Emit a redacted JSON report to stdout instead of human-readable output             |
| `--no-color` | Disable ANSI color in human output                                                 |
| `--ascii`    | Use ASCII status labels (`OK` / `WARN` / `FAIL`) instead of `ok` / `warn` / `fail` |

## Sharing a report safely [#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:

```bash
cluster doctor --json > cluster-doctor.json
```

## Exit code [#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 [#next-steps]

* **[Config basics](/docs/build/config/basic)** — settings in
  `config.toml`, plus [MCP servers and custom skills](/docs/build/config/advanced).
* **[Exec & sessions](/docs/build/exec)** — run prompts non-interactively and
  manage saved sessions.