CLI Reference
Purpose #
Quick-lookup table of every aidokit command, the global flags, exit codes, and output formats. The authoritative spec is .docs/docs/specs/cli-reference.md; this page links and summarises.
Big Picture #
aidokit is the unscoped CLI binary; libraries are @aidokit/*. Global flags work with every command. Exit codes use a grouped taxonomy. --json mode produces structured output.
Global flags #
| Flag | Short | Default | Notes |
|---|---|---|---|
--help |
-h |
false | Print help; exit 0 |
--version |
-v |
false | Print CLI version; exit 0 |
--yes |
-y |
false | Accept prompts with defaults. Does NOT bypass security-sensitive prompts or prereq installs. |
--no-prompts |
false | Fail if input is required | |
--dry-run |
false | Show what would happen; no writes, no shell | |
--json |
false | Emit machine-readable JSON; implies --no-color and --no-prompts |
|
--verbose |
false | Step-by-step output | |
--quiet |
-q |
false | Suppress non-error output |
--no-color |
false | Disable ANSI colour | |
--cwd <path> |
pwd | Run as if invoked from <path> |
|
--config <path> |
auto | Use specified config file |
--verbose and --quiet are mutually exclusive (CLI rejects with exit 2).
Commands #
v0.1 surface #
| Command | Purpose |
|---|---|
aidokit init [--adapter <name>] [--conformance <level>] [--stack <ids>] [--no-beads] [--no-mcp] [--dry-run] [--yes] |
Bootstrap a project (interactive prompts otherwise) |
v0.5 surface (shipped, see CHANGELOG [0.5.0]) #
| Command | Purpose |
|---|---|
aidokit init --brownfield |
Scan for existing PRD/BRD/code; offer to ingest |
aidokit doctor [--fix-hints] [--strict] |
Read-only health check |
aidokit sync [--scripts] [--skills] [--agents] [--dry-run] |
Re-emit adapter-owned files; never overwrites user files silently |
aidokit validate <artifact-path> [--schema <name>] |
Validate an artifact against its JSON schema |
aidokit migrate <from>-to-<to> [--backup-dir <path>] [--review] |
Run a registered migration script |
aidokit mcp list \| add \| remove \| scope \| suggest |
Manage MCP servers |
aidokit skills list \| add \| personal init/add/list |
Manage skills (project and personal) |
aidokit new task \| adr \| skill \| capability |
Scaffold artifact templates |
aidokit manifest [--json] |
Print project's adapter.md manifest |
aidokit list adapters \| stack-packs |
List installed extensions |
v1.0 additions #
| Command | Purpose |
|---|---|
aidokit init --adapter codex / --adapter copilot |
Codex / Copilot adapters |
aidokit init --adapter claude-code,codex,copilot |
Multi-adapter project |
aidokit init --tier starter\|standard\|strict |
v1.0 preferred way to choose workflow intensity (A2). --conformance works as back-compat alias |
aidokit add adapter <name> [--dry-run] |
Add an adapter to an existing project (D1+D2). Skip policy; refreshes .aidokit/capabilities.json at Strict |
aidokit search adapter [<query>] [--verified-only] |
npm-native discovery |
aidokit search stack-pack [<query>] [--verified-only] |
npm-native discovery |
Recently added (sessions 2–10) #
| Command | Purpose |
|---|---|
aidokit doctor --drift [--max-adr-age-days <n>] [--no-semantic-drift] |
(C7 + SP10) Adds stale-ADR, task-backlog, and semantic doc-graph drift checks (broken file refs, missing symbol refs). Opt out of the semantic pass with --no-semantic-drift |
aidokit doctor --hygiene |
(SP9) Scratchpad freshness + brief↔commit drift checks |
aidokit doctor --model-drift |
(SP8) Compares declared adapter cliVersion against .aidokit/model.lock |
aidokit verify [--capabilities] [--secrets] [--budget] [--deps] [--license] [--loop-cap] [--all-facets] [--all] [--sarif] |
(G5 + D4) Read-only install integrity check; --capabilities adds the D4 declared-vs-actual cross-check; facet flags run the umbrella facets (ADR-0018) |
aidokit eval [--task <id>] [--brief <path>] |
Run the ## Acceptance criteria block of a task brief; reports PASS / FAIL / NO_CRITERIA |
aidokit manifest [--json] [--verify-capabilities] |
(D6) Print project manifest; --verify-capabilities integrates the D4 verifier and exits non-zero on drift |
aidokit metrics summary [--since <Nm\|Nh\|Nd\|Nw>] [--path <file>] |
(C3) Aggregate the local-only MetricsLog (agent-artifacts/metrics/events.jsonl) |
aidokit metrics export [--since <…>] [--path <file>] [--output <file>] |
(C4) Raw events as JSON to stdout (or to a file). The "manual telemetry" path |
aidokit audit export --format soc2\|eu-ai-act [--output <file>] |
(C5+C6) Strict-tier evidence packet. Pair with docs/compliance/<format>.md |
For each command's full synopsis, prompts, behaviour, and examples, see .docs/docs/specs/cli-reference.md §7.
aidokit verify facets #
aidokit verify is a pluggable facet runner (ADR-0018). All facets share .aidokit/policy.json and emit findings under stable codes (see error-codes.md). Use --all-facets (or --all) to run every facet; pass individual flags to scope. Output can be emitted as SARIF with --sarif.
| Facet flag | What it does |
|---|---|
--secrets |
11 bundled credential patterns + Shannon-entropy fallback + path/inline allowlist. Operates on the staged diff (default) or the full tree (--all). |
--budget |
Reads agent-artifacts/metrics/events.jsonl token ledger; converts via the usdPerMillionTokens policy; compares against maxUsdPerTask. |
--deps |
Diffs package.json against HEAD; flags new dependencies not in allowedScopes and not justified in a change-summary ## Dependencies section. |
--license |
SPDX header detection (when requireHeaders: true) plus node_modules license lookup. No network access. |
--loop-cap |
Reads iterations from agent-artifacts/<task-id>/state.json; emits LOOP_CAP_EXCEEDED / LOOP_CAP_NEAR_LIMIT. |
aidokit eval #
Runs the ## Acceptance criteria block from a task brief and reports per-criterion PASS / FAIL.
Flags:
--task <id>— locate the brief via Beads task id.--brief <path>— point directly at a brief file.
Criterion syntax inside the brief:
- [ ] manual task description— manual criterion (always reported asMANUAL).- [ ] > <argv-split command>— shell criterion. The>marker introduces a command parsed argv-style (no shell expansion); exit 0 is PASS, anything else FAIL.
Exit codes: 0 all criteria PASS · 1 any FAIL · 2 brief contains no criteria (NO_CRITERIA).
init flag matrix (recap) #
| Flag | Notes |
|---|---|
--tier <name> |
starter | standard | strict. Preferred over --conformance. Asks interactively if omitted. |
--conformance <…> |
Back-compat alias of --tier (minimum ↔ starter, standard ↔ standard, strict ↔ strict). |
--adapter <names> |
Comma-separated for multi-adapter projects. |
--stack <ids> |
Comma-separated stack-pack ids; defaults to auto-detection. |
--brownfield |
Allows init on a project with hand-rolled .claude/ etc. Does not override an existing aidokit install — that requires deleting .aidokit/state.json (B5). |
--no-beads |
Skip Beads. Default at Starter tier (A3); Standard / Strict prompt or default on. |
--no-mcp |
Skip MCP install. Suppressed at Starter tier (A3). |
--dry-run |
Show file plan; no writes. |
Exit codes #
| Code | Group | Meaning |
|---|---|---|
| 0 | Success | Command completed successfully |
| 1 | Generic error | Unhandled or uncategorised |
| 2 | Bad invocation | Unknown flag, missing argument, mutually-exclusive flags |
| 10 | Prereq missing | |
| 11 | Adapter | Not found, failed to load, version-incompatible |
| 12 | Stack pack | Not found or failed to load |
| 13 | Conformance | Harness or doctor check failed |
| 20 | Filesystem | File write/read/permission failure |
| 21 | MCP | Install/remove command failed |
| 30 | Migration | Migration script failure |
| 40 | User | Cancelled an interactive prompt |
| 50 | Network | Network operation failed |
| 60 | Validation | Schema validation failed |
| 70 | Conflict | Sync conflict not approved |
See error-codes.md for the full AidoError.code ↔ exit-code map.
Output formats #
Human (default) #
✔ success, ✘ failure, ⚠ warning, ℹ info. Spinners (ora) for in-progress operations. Colour gated by TTY + NO_COLOR + --no-color.
--json #
Exactly one JSON object on stdout. All logs / progress to stderr.
Success:
{ "ok": true, "command": "init", "result": { "adapter": "claude-code", "conformance": "standard", "filesWritten": 47, "mcpsInstalled": 3, "nextSteps": ["claude", "/intake \"describe your project\""] } }
Error:
{ "ok": false, "command": "init", "error": { "code": "PREREQ_MISSING", "exitCode": 10, "message": "...", "details": { "prereq": "claude-code", "minVersion": "2.1.32" }, "hint": "Install Claude Code via: ..." } }
--verbose #
Adds a steps array with timestamped step transitions.
Environment variables #
| Variable | Purpose |
|---|---|
AIDO_HOME |
Override personal config (default ~/.aido/) |
AIDO_LOG_LEVEL |
error / warn / info / debug / trace |
AIDO_NO_UPDATE_CHECK |
Skip newer-version checking |
AIDO_OFFLINE |
Refuse any network operation |
NO_COLOR |
Standard convention; disables colour |
CI |
Detected from common CI vars; implies --no-prompts defaults |
DEBUG |
Standard debug namespace pattern (aidokit:*) |
Configuration files #
| Path | Owner | Purpose |
|---|---|---|
<project>/.aido/adapter.md |
CLI | Adapter, version, conformance, spec version |
<project>/.aido/state.json |
CLI | Selected MCPs, sync history, audit log |
<project>/.aido-staging/ |
CLI | Transient staging directory |
~/.aido/config.json |
User | Preferences |
~/.aido/personal-skills/ |
User | Cross-project skills |
Related Pages #
- .docs/docs/specs/cli-reference.md — authoritative spec
- error-codes.md
- ../concepts/release-and-distribution.md