CLI command surfaces

Progressive disclosure for the agent-toolkit CLI: everyday consumer commands vs advanced workstation harness commands.

Related: SCOPE.md (product boundary), issue #48 (consumer-first split), issue #84 (advanced runtime de-emphasis).

Consumer commands

Install, verify, and sync toolkit content for coding assistants:

Command	Purpose
install	Install profiles for detected or selected AI tools
update	Refresh installed profiles from latest toolkit data
uninstall	Remove toolkit-owned files using install receipts
doctor	Check toolkit data and tool availability
diff	Show changes vs installed plugin bundles
skills	Sync, list, and validate skills
mcp	MCP provider setup, health, doctor, uninstall
plugin	Plugin bundle sync and check

Also: version, help, completion (bash/zsh/fish/PowerShell).

Advanced commands

Multi-repo workspace harness, loop automation, and maintainer tooling. Still available on the same binary — de-emphasized in top-level help:

Command	Purpose
loop	Loop engineering: init, run, status, audit, cost, schedule, sync
workspace	Workspace scaffolding: init, context, sync
memory	Knowledge base: add, search, inject, review, todo
project	Project index: clone, list, add, remove, scan
devcompanion	Background job queue (dc alias)
insights	AI tool usage insights — opencode, cursor, claude, windsurf, copilot, codex, all
serve	Programmatic/headless API server (vlib/veb) — capability discovery, read/execution APIs, jobs, OpenAPI, selfcheck; 127.0.0.1:3847 default, AGENT_TOOLKIT_TOKEN for remote
build	Compile canonical capabilities into target artifacts
inventory	List skills, agents, and products
matrix	Platform capability matrix
release	REMOVE — release artifacts (CI / docs/RELEASING.md); #527
swarm	Multi-agent swarm orchestration (pair/team/full, Herdr/tmux, budgets, handoffs)

Swarm details: docs/SWARMS.md, docs/SWARM_ARCHITECTURE.md.

V-port dispositions for advanced commands: docs/v/advanced-command-disposition.md (#560).

Migration

Existing scripts invoking advanced commands continue to work unchanged. New users should start with install, doctor, and skills only; adopt advanced commands when running an ai-workspace-style harness.

Migration inventory (#475)

Authoritative index of every top-level command — 22 capability entries in docs/compatibility/cli-contract.yaml (#549, closed). Machine-readable flags, stdin/stdout/stderr, exit codes, env, effects, and tests live in the contract YAML — do not duplicate here. release is REMOVE (stub exits 1, #527) — retired command carries no contract entry (ADR-030). insights was DEPRECATE #526 but re-ported in 1.26.0 as thin wrapper over bin/tool-insights.

Disposition for advanced commands: v/advanced-command-disposition.md (#560). Wave/complexity/risk in the YAML migration: block.

Command	Surface	Owner	Disposition
help	meta	—	keep
version	meta	#555	PORT (V canonical)
install	consumer	#607	PORT
update	consumer	ADR-017	PORT (capability-only)
uninstall	consumer	#461	PORT
doctor	consumer	#514	PORT
diff	consumer	#515	PORT
skills	consumer	#517	PORT
mcp	consumer	#518	PORT
plugin	consumer	#519	PORT
completion	consumer	#544	PORT
loop	advanced	#523	REDESIGN
workspace	advanced	#520	PORT
memory	advanced	#521	PORT
project	advanced	#522	PORT
devcompanion	advanced	#525	PORT
insights	advanced	#526	PORT (re-ported 1.26.0 — wrapper over bin/tool-insights, supports opencode/cursor/claude/windsurf/copilot/codex/all)
build	advanced	compiler EPIC	PORT (V build exists)
inventory	advanced	#516	PORT
matrix	advanced	compiler EPIC	PORT
release	advanced	#527	REMOVE (CI / docs/RELEASING.md)
swarm	advanced	#524	REDESIGN
serve	advanced	#833	PORT

JSON/--json and full flag lists: cli-contract.yaml, not this table.

Exit-code contract (#48)

Consumer and advanced commands return integer status codes from their cmd_* handlers. They must not call sys.exit for recoverable errors (missing templates, unknown --tools values). argparse --help stays exit 0; bad flags stay exit 2.