> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getunbound.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Doctor

> Deep local health check for your Unbound install and connected AI tools

`unbound doctor` runs a deep diagnostic of your local Unbound install. It inspects every supported AI coding tool — Cursor, Claude Code, Codex, GitHub Copilot, and Augment Code — and validates that your stored API key is still accepted by the backend.

```bash theme={null}
unbound doctor
```

## What it checks

For **each AI coding tool**, doctor verifies three things:

| Check           | What it confirms                                                               |
| --------------- | ------------------------------------------------------------------------------ |
| **Config**      | The tool's own config file contains the Unbound integration                    |
| **Hook script** | The installed hook / key-helper file exists on disk                            |
| **Env wiring**  | The API key — and the gateway URL for gateway mode — is exported in your shell |

It also validates your stored **API key** against the backend, so a revoked or expired key is caught here rather than at your next tool call.

For **Claude Code** and **Codex**, doctor reports the active **mode** (subscription vs gateway).

## Per-tool status

Each tool resolves to one of four statuses:

| Status             | Meaning                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Healthy**        | Config, hook script, and env wiring all present (shown in green)                                                                                        |
| **Tampered**       | Installed but broken — a missing hook, a config without the integration, or a managed config that points at a hook that isn't on disk. Reinstall to fix |
| **Not set up**     | No Unbound integration found for this tool                                                                                                              |
| **Managed by MDM** | Configured org-wide by an admin (config **and** hook verified)                                                                                          |

Doctor always tells you the next step:

* **Nothing set up yet** → run `unbound setup`.
* **A user-level tool is tampered** → run `unbound doctor --fix` (no sudo needed).
* **An MDM-managed install is broken** → it's org-wide, so run `sudo unbound doctor --fix` to reinstall the managed hooks.
* **API key invalid** → run `unbound login`.

## Exit codes

| Code     | Meaning                                                                     |
| -------- | --------------------------------------------------------------------------- |
| `0`      | All tools healthy (or not installed / MDM-managed) and the API key is valid |
| non-zero | Any tool is **Tampered** or the API key is invalid                          |

The non-zero exit lets you gate scripts or CI on a clean install.

## Flags

| Flag     | Behavior                                                                                                                                                                                                                                                                                           |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--fix`  | Reinstall the tampered tools the current scope can repair. **Without `sudo`** it fixes your user-level tools; **with `sudo`** (`sudo unbound doctor --fix`) it reinstalls the MDM-managed (org-wide) hooks. Whichever scope you run, doctor points you at the other for anything it couldn't touch |
| `--json` | Machine-readable output (per-tool `status`, `checks`, `conflict`, plus `api_key`)                                                                                                                                                                                                                  |

The JSON mirrors the human report. Each tool carries its `status`, the individual `checks`, and a boolean **`conflict`** — `true` when two modes of the same tool are installed at once (for example Claude Code in **both** subscription and gateway mode), which doctor reports as **Tampered** so `--fix` can clean it up. `api_key` carries the key-validation result (`valid` / `invalid` / `not-logged-in` / `unverified`).

## Examples

```bash theme={null}
# Full health check
unbound doctor

# Repair every tampered tool automatically
unbound doctor --fix

# Machine-readable output for scripts / CI
unbound doctor --json
```