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 codex,copilot,claude-code |
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 doctor --rules |
(ROI #9) Rules File Optimizer — flags duplicate blocks, oversized files (>400 lines), and conflicting directives across CLAUDE.md / AGENTS.md / .github/copilot-instructions.md. All findings warn. |
aidokit doctor --conflicts |
(#17) Instruction Conflict Detector — scans rules files, engine skill SKILL.md files (.claude / .codex / .copilot), and agent-artifacts/task-briefs for contradictory directives. Emits CONFLICT_DIRECTIVE (warn) or CONFLICT_OK (pass). |
aidokit doctor --budget-map |
(#3/#4) Context Budget Map — statically reads <engine>/agents/*.md and reports per-role line/byte counts plus heuristic skill/MCP/doc reference counts (markdown links + frontmatter mcp entries). Emits BUDGET_MAP (pass, informational) per role and BUDGET_OVERSIZED (warn) when a role file exceeds 300 lines. |
aidokit doctor --model-policy |
(ADR-0022) Model Policy — validates .aidokit/model-policy.json (advisory per-task-type model recommendations). Emits MODEL_POLICY_ABSENT (pass), MODEL_POLICY_INVALID (warn), or MODEL_POLICY_OK (pass). aidokit recommends; it never selects a model. |
aidokit doctor --all |
Convenience — runs every opt-in check at once (--drift --hygiene --model-drift --rules --conflicts --budget-map --model-policy). The single command for the whole doctor surface. |
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 |
aidokit mcp risk [--json] |
(#16) Read-only risk report for installed MCPs — per server: the catalog's declared securitySensitive and untrustedOutput signals (reported verbatim, not derived) plus suggested roles. Catalog ids not found show as unlisted (unknown risk). No network |
aidokit task score [id\|path] [--brief <path>] |
(#10) Deterministic task-brief quality score (0–100 + A–F grade) against the ADR-0021 rubric. Resolves the brief like aidokit eval. Advisory — always exits 0 |
aidokit task run [id\|path] [--brief <path>] |
(ADR-0027, Tier-2 chain) Runs the deterministic pre-flight in order — score → goal draft → goal plan — then stops before the model. Prints the artifacts and the ordered next steps (run your adapter → eval → verify → pr packet). Composition only; never invokes a model. |
aidokit goal draft [id\|path] [--brief <path>] |
(#1/#2 + ADR-0023) Statically extract a goal contract (objective, allowed files, validation commands, stop rules) from a task brief into agent-artifacts/goals/<id>-goal.md. Zero model calls |
aidokit goal plan [id\|path] [--brief <path>] |
(#1/#2 + ADR-0023) Write a commented run-plan shell script to agent-artifacts/goals/<id>-plan.sh (draft goal → run YOUR adapter manually → aidokit eval → aidokit verify → human review). The script never invokes a model |
aidokit handoff pack [--task <id>] [--brief <path>] |
(#5/#6) Compress available artifacts (task brief + recent change summaries + recent git log) into a resume packet at agent-artifacts/handoff/<id-or-timestamp>.md. Purely static text assembly; zero model calls |
aidokit intent build |
(#5/#6) Compile a static intent doc .aidokit/intent.md from existing docs: .docs/ARCHITECTURE.md section headings + workspace package list + ADR titles. Purely static; zero model calls |
aidokit index build |
(#19/#20 + ADR-0024) Build a local-only deterministic project index (files, exports, tests, docs) from a read-only scan of packages/*/src, plus *.md under docs/ and .docs/. Writes .aidokit/index.json with stable sorted keys and 2-space indent. Zero network, zero model calls |
aidokit baseline capture --from <file> / aidokit baseline diff --from <file> |
(#12/#21 + ADR-0025) Deterministic known-broken baseline. capture parses a test-output file (TAP not ok / plain FAIL/FAILED lines) and writes the sorted failing set to .aidokit/baseline.json. diff classifies a new output file into pre-existing vs new failures (exits 1 on new). aidokit never runs your tests — it parses a file you provide. Zero model calls |
aidokit pr packet [--task <id>] [--brief <path>] [--base <ref>] [--output <file>] [--force] |
(#13 + ADR-0026) Assemble a markdown PR packet (summary, changed files from git diff --name-only main...HEAD, linked task brief Goal/Validation/Risks/Rollback) to stdout or --output. --output refuses to clobber an existing file without --force. Zero model calls |
aidokit ci init --provider github\|gitlab\|bitbucket [--force] |
(#14 + ADR-0026) Emit a CI config (.github/workflows/aidokit.yml, .gitlab-ci.yml, or bitbucket-pipelines.yml) running pnpm -r build, pnpm -r test, and aidokit verify --all-facets. Read-before-write: refuses to clobber without --force |
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