ak doctor

Run AgentKit health checks, interpret the nested JSON report, and opt into repair or exit-code gating safely.

Use ak doctor to check the AgentKit installation after setup or an update, or when a runtime, kit, registry session, or local dependency behaves unexpectedly. The command reports health without changing disk by default. Incomplete first-run setup or a missing CLI session can warn as onboard_incomplete with suggested ak onboard or ak login. When updates.channel and kit.channel both exist and differ, channel_drift warns and suggests ak onboard --channel with the binary channel.

The read-only auto_update check, shown as Auto-update, reports the background auto-update schedule, the last result, a stuck or overdue run, and opted-in projects that can no longer be updated; it warns with a suggested ak update command when one of those needs attention.

Usage

ak doctor

The command accepts no positional arguments.

Command flags

Flag	Default	Description
`--adapter <name>`	Empty	Filter checks to an adapter with a dedicated doctor suite: `claude-code`, `codex`, or `cursor`.
`--check <names>`	Empty	Run named checks as a comma-separated list, such as `binary_version,codex_binary_present`.
`--exit-on-fail`	`false`	Exit `1` when any completed check fails.
`--fix`	`false`	Attempt available fixes for failing checks.
`--list`	`false`	List registered check names and exit.
`--offline`	`false`	Skip the `binary_version` and `network` checks.

Shared flags such as --json, --no-interactive, --quiet, --verbose, and --yes are described in CLI conventions.

Common examples

Read a human report

ak doctor

The report groups checks by subsystem and separates actionable warnings from Notes. Its summary is Summary: N ✓ N ⚠ N ✗ N ◦; the Notes segment is omitted when there are none.

Expand advisory Notes

ak doctor -V
ak doctor --check kit_integrity

Advisory warning bodies are collapsed by default as N notes - rerun with -V for details (or 1 note ...). -V/--verbose and an explicit --check expand them; --adapter alone does not. Commands from hidden Notes are excluded from Quick Commands. Notes are not success or failure: they cover advisory states such as a missing integrity manifest, while integrity drift and active conflicts remain actionable.

Gate automation on health

Choose either the structured health field or an explicit exit-code gate:

ak doctor --json | jq '.data.healthy'
ak doctor --exit-on-fail

The JSON health field is .data.healthy, not .healthy.

Discover and run focused checks

ak doctor --list
ak doctor --check disk_space
ak doctor --check binary_version,network
ak doctor --adapter codex

An unknown check name is a command error rather than an empty healthy result.

Run without network checks

ak doctor --offline

Without --offline, the full suite includes network-dependent checks. Offline mode skips those checks; it does not turn skipped results into successful network verification.

Apply fixes safely

ak doctor --fix can run suggested repair commands that modify AgentKit or runtime files. On an interactive terminal, it asks before each available fix.

For an intentional unattended repair, include --yes explicitly:

ak doctor --fix --yes --json

Do not treat --fix --json or --fix --no-interactive as prompt-free unless you also pass --yes. Without --yes, the current fix path can still read process stdin. End-of-file skips a fix, while piped confirmation can apply it.

Review suggested commands before approving them. A fix is rechecked after it runs, and a failed repair remains visible in the final report.

Automation output

Successful JSON output uses a versioned envelope on stdout:

schema_version: 1
kind: doctor.report
data.schema_version: 1
data.checks: array of check results; advisory rows include advisory: true
data.summary: total, ok, warn, fail, and skip counts
data.healthy: boolean

Each check can report a name, status, evidence, a suggested fix command, and additional details. advisory: true is present only on advisory rows; false is omitted. Advisory rows retain status: "warn", and summary.warn includes both actionable warnings and Notes. There is no summary.notes field. Gate on the outer schema_version and kind before reading data.

JSON-mode failures, including flag-parse errors (exit 2), end stderr with the shared error envelope.

Exit behavior

Exit	Meaning	What to do
`0`	The selected checks completed, whether healthy or unhealthy.	Read `.data.healthy` in JSON or the human summary.
`1`	The command failed, a check name was unknown, or `--exit-on-fail` found an unhealthy result.	Correct the check name, inspect the error, or act on the failing checks.
`2`	Flags or arguments were invalid.	Correct the invocation before retrying.

The default unhealthy result is therefore not a process failure. Notes do not change healthy, --exit-on-fail, --fix, or exit classification. Use --exit-on-fail only when process status should represent health.

Verify and recover

After a repair, rerun the affected check without --fix:

ak doctor --check <check-name>

If a suggested repair changes kit or runtime files, keep any recovery snapshot reported by that underlying command and verify the target runtime before removing recovery data. Do not repeat repairs with --force as a first step.

On this page