AgentKit CLI reference

Find the ak command that matches your outcome, then review its exact syntax, effects, output, and recovery guidance.

Use this reference when you know what you want to accomplish and need the exact ak command, flags, output contract, or exit behavior. If you are setting up AgentKit for the first time, start with the quickstart instead.

Browse by outcome below, or use the CLI Reference sidebar to open any command.

Command and help scope does not guarantee identical runtime behavior across releases. Read each command page's effects, output, and exit guidance before using it in automation.

Find a command by outcome

Outcome	Start with	Typical commands
Configure access and preferences	Account and configuration commands	`ak login`, `ak whoami`, `ak licenses`, `ak setup`, `ak config`
Create or register a project	Project lifecycle commands	`ak init`, `ak new`, `ak projects`
Install runtime capabilities	Kit and component commands	`ak kit`, `ak skills`, `ak agents`, `ak commands`, `ak skill`
Run and inspect work	Execution and activity commands	`ak run`, `ak activity`, `ak sessions`, `ak content`, `ak data`, `ak analytics`
Supervise external CLI job graphs	Orchestration commands (Darwin only)	`ak orchestrate start`, `ak orchestrate status`, `ak orchestrate resume`, `ak orchestrate stop`
Plan and connect tools	Planning and integration commands	`ak plan`, `ak journal`, `ak mcp`, `ak api`, `ak watch`
Diagnose and recover	Health and recovery commands	`ak doctor`, `ak audit`, `ak diagnostics`, `ak backups`, `ak recover`, `ak migrate`
Update or remove installations	Maintenance commands	`ak update`, `ak self-update`, `ak versions`, `ak changelog`, `ak uninstall`

Some commands support more than one outcome. Open the command page for exact paths, flags, and subcommands.

Common workflows

Check installation health

Run a health report and inspect the nested health field:

ak doctor --json | jq '.data.healthy'

Use ak doctor --exit-on-fail when a failing health check must produce a non-zero process exit. See ak doctor for its network, repair, output, and exit behavior.

Prepare a project and install a kit

Use different commands for different lifecycle outcomes:

# Register AgentKit ownership in an existing directory.
ak init

# Create a new project directory.
ak new my-project

# Install a kit into a selected runtime.
ak kit init engineer --target codex

See ak kit init before scripting an install.

Update the right layer

# Check only the AgentKit binary.
ak self-update --check

# Preview or apply the unified update workflow.
ak update

# Refresh one installed kit route.
ak kit refresh engineer --target codex --yes

The binary, unified updater, and kit refresh have different effects and confirmation behavior. Match the command to the layer you intend to change.

Inspect recovery snapshots

ak backups list
ak backups show <id>
ak backups verify <id>
ak recover <id> --dry-run

Recovery snapshots are bounded to captured AgentKit-managed surfaces. They are not full-machine backups, and a multi-file restore is not transactional.

Use commands safely

Review command-local behavior: Global flags do not make every command use the same confirmation, JSON, or exit contract.
Treat --json as an output choice: It implies noninteractive mode, and some mutation commands can proceed without an additional prompt.
Use --yes intentionally: Add it only after reviewing the exact target, scope, mode, and operation. It is not required by every mutation path.
Do not equate preview with offline: Some remote workflows can contact the registry, renew authentication, download artifacts, or populate verified cache before changing their primary target.
Preserve recovery data: Keep any reported snapshot ID or manual recovery path until you have verified the result.
Avoid broad cleanup: Do not delete entire runtime or AgentKit home directories to recover one command.

Syntax and global behavior

Read CLI conventions for shared flags and presentation modes. Then use the individual command page for exact arguments, local flags, effects, output streams, and classified exits.

On this page