2.4.1-beta.1) — updated automatically on every beta release.Switch to stable →CLI commands
ak doctor
Run health checks on the AgentKit installation
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.
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/.
Usage
ak doctor [flags]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 checksFlags
| Flag | Description |
|---|---|
--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 |
Output modes
| Mode | Behavior |
|---|---|
pretty | default on TTY (colors, ASCII markers) |
plain | auto when stdout piped or --no-interactive |
json | --json (single-object envelope, NDJSON-safe) |
Exit codes
| Code | Meaning |
|---|---|
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 |
Related commands
ak— AgentKit CLI