Skip to main content
unbound doctor runs a deep diagnostic of your local Unbound install. It inspects every supported AI coding tool — Cursor, Claude Code, Codex, and GitHub Copilot — 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 three things:
CheckWhat it confirms
ConfigThe tool’s own config file contains the Unbound integration
Hook scriptThe installed hook / key-helper file exists on disk
Env wiringThe 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:
StatusMeaning
HealthyConfig, hook script, and env wiring all present (shown in green)
TamperedInstalled 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 upNo Unbound integration found for this tool
Managed by MDMConfigured 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

CodeMeaning
0All tools healthy (or not installed / MDM-managed) and the API key is valid
non-zeroAny tool is Tampered or the API key is invalid
The non-zero exit lets you gate scripts or CI on a clean install.

​
Flags

FlagBehavior
--fixReinstall 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
--jsonMachine-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

# Full health check
unbound doctor

# Repair every tampered tool automatically
unbound doctor --fix

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