ak doctor

ak doctor

Run health checks on the AgentKit installation

Synopsis

What it does: Read-only health check that inspects every AgentKit subsystem (binary version, kit integrity, skill envs, project registry, API keys, network reachability, and disk space) and prints the status of each check. Checks run concurrently and finish in < 5s. Exits 0 even if checks fail - inspect the healthy field in --json output or pass --exit-on-fail if you want CI to gate on check failures.

Who it's for: Both: power devs (--json for CI monitoring) and non-technical users (interactive colour summary with suggested fixes).

When to use it: Run after installation, after an upgrade, or when something unexpected happens. Use in CI with --json to alert on health drift.

Examples: ak doctor # full interactive check ak doctor --json # machine-readable output for CI (exit 0 always) ak doctor --json | jq .healthy # branch on health in scripts ak doctor --exit-on-fail # exit 1 on failure (classic CI mode) ak doctor --check api_keys # run a single check ak doctor --list # list valid --check names (supports --json) ak doctor --fix # attempt auto-repair with confirmation ak doctor --fix --yes # auto-repair without confirmation ak doctor --offline # skip network checks

What changes on disk: Read-only by default. With --fix, may invoke repair commands (e.g. ak setup, ak kit refresh engineer --remote --global --yes, ak skill repair engineer/web-testing) that write to ~/.agentkit/ or ~/.claude/plugins/.

Output modes: pretty default on TTY (colors, ASCII markers) plain auto when stdout piped or --no-interactive json --json (single-object envelope, NDJSON-safe)

Exit codes: 0 success 1 runtime error 2 invalid flags 3 user-cancel (SIGINT, prompt-cancel) 0 checks completed (healthy or not); parse healthy field for status 1 command itself failed (I/O error, invalid check name); or --exit-on-fail with failing checks 2 invalid flags

ak doctor [flags]

Options

      --adapter string   Filter checks to a specific adapter: codex, claude-code
      --check string     Run only the named check(s), comma-separated (e.g. binary_version,codex_binary_present)
      --exit-on-fail     Exit 1 when any check fails (default: exit 0, check healthy in --json output)
      --fix              Attempt automated fixes for failing checks (confirm each unless --yes)
  -h, --help             help for doctor
      --json             Emit machine-readable JSON (implies --no-interactive)
      --list             List the registered check names (valid --check values) and exit
      --no-interactive   Disable interactive prompts (CI-safe)
      --offline          Skip network-dependent checks (binary_version, network)
  -q, --quiet            Suppress non-error output on stderr
  -V, --verbose          Extra diagnostic output on stderr (loses to --quiet)
  -y, --yes              Assume yes for all prompts

SEE ALSO

• ak - AgentKit CLI