Doctor

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

unbound doctor

What it checks

For each AI coding tool, doctor verifies:

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
Healthy · managed by MDM	Configured org-wide by an admin, with the managed config and its hook verified. `--json` reports this as `managed-by-mdm`

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, the stored API key is rejected, `CLAUDE_CONFIG_DIR` is set to an empty string, or `CLAUDE_CONFIG_DIR` points at a directory with no Unbound install while `~/.claude` holds one

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`, a top-level `healthy` boolean, `key_validations_skipped`, `claude_config_dir_blank` and `claude_config_dir_mismatch`)

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

# Full health check
unbound doctor

# Repair every tampered tool automatically
unbound doctor --fix

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

Getting Started

CLI

Policies

Analytics

Integrations

MDM Integrations

Connections

Support & Troubleshooting

What it checks

Per-tool status

Exit codes

Flags

Examples

​What it checks

​Per-tool status

​Exit codes

​Flags

​Examples

What it checks

Per-tool status

Exit codes

Flags

Examples