$ aidlc — CLI Reference
Generated from the shipped CLI (30 commands). Requires Node.js >= 22.13.0. Install with npx @rasensio/aidlc init.
Test traceability is configured via traceability.test_globs; the gate command parses tasks.md checkboxes [tasks] and reports done/total task completion at the implementation gate.
$ aidlc add [command]
Add framework components
$ aidlc add action <description>
Create a lifecycle action from a natural language description
| Option | Description |
|---|---|
| --event <event> | Override the inferred lifecycle event |
| --blocking | Mark the action as blocking (halts transition on failure) |
| --non-interactive | Skip confirmation prompts; fail if event cannot be inferred |
| --dry-run | Show what would be added without writing |
$ aidlc add skill [name]
Create an app-owned operational skill and package it per platform
| Option | Description |
|---|---|
| --description <text> | One-line summary of the operation |
| --steps <text> | The operation steps, as markdown |
| --trigger <text> | When this skill should be used |
| --paths <paths...> | Repo-relative paths the skill operates on |
| --overwrite | Replace an existing skill of the same name |
| --re-emit | Re-package existing skills; refreshes verification text |
| --check | Smoke-check existing skills without writing |
| --dry-run | Show what would be written without writing |
$ aidlc amend <instance>
Record a requirements amendment and reopen the phases it invalidated
| Option | Description |
|---|---|
| --impact | Report remaining citations of the retired criteria; write nothing |
| --amendment <n> | Operate on this amendment instead of the highest-numbered one |
| --confirm | Confirm a reopen from testing or later |
| --override | Write without a live claim (records `by` from the environment) |
| --json | Output as JSON |
$ aidlc autopilot [command]
Work the backlog in the background: set up, run, watch, pause, stop
$ aidlc autopilot answer <fingerprint> <option>
Apply your answer to one pending entry and record it, so no session asks it again
| Option | Description |
|---|---|
| --note <text> | Your words: the reason for a park or decline, or the answer for "other" |
| --rank <n> | For a triage backlog answer: the rank to give it instead of the one offered |
| --by <name> | Who answered (default: git config user.name) |
$ aidlc autopilot approve <instance>
Approve the phase an item paused after for review, so the run carries it on
$ aidlc autopilot forget <instance>
Stop tracking an item you finished or abandoned by hand
$ aidlc autopilot pause
Freeze the run and its agents in place, e.g. before closing the laptop
$ aidlc autopilot pending
List every decision the run waits on you for, each with its options and the command that applies it
| Option | Description |
|---|---|
| --json | Print {run, entries} as JSON |
$ aidlc autopilot resume
Continue a paused run from where it was frozen
$ aidlc autopilot review <instance>
Keep, reject or promote each decision an unattended run logged for an item, in the checkout you run it in
$ aidlc autopilot run
Start a background run over the next items, and return
| Option | Description |
|---|---|
| --items <n> | Stop after this many items are released or held |
| --all | Keep going until nothing is ready and nothing is in flight |
| --interval <seconds> | Seconds between passes (default: "60") |
| --stop-at <step> | For the items this run starts, the last step autopilot takes: pr, merge, release |
| --pause-after <phases> | For the items this run starts, pause for review after: comma-separated phases from requirements, design, implementation, testing, or "none" |
$ aidlc autopilot setup
Choose the agent, how many items build at once, a cost cap, where autopilot stops for you, and the release step
| Option | Description |
|---|---|
| --agent <preset> | Agent preset (claude-scoped, claude-full, codex-full-auto) |
| --parallel <n> | Items building at once: 1 or 2 |
| --token-cap <tokens> | Stop an item past this many tokens (40M, 500k), or "none" |
| --cost-cap <usd> | Stop an item past this many dollars of API price, or "none" |
| --pause-after <phases> | Pause for review after: comma-separated phases from requirements, design, implementation, testing, or "none" |
| --stop-at <step> | The last step autopilot takes: pr, merge, release |
| --release <preset> | After a merge: repo-script or merge-only |
| --non-interactive | No prompts; recommended choices for anything not flagged |
$ aidlc autopilot status
Show the active run and every tracked item
| Option | Description |
|---|---|
| --watch | Redraw every 2 seconds until the run ends; q or Ctrl-C leaves the run running |
| --view <name> | With --watch: cards (default), table or lanes; v switches while watching |
$ aidlc autopilot stop
Stop the run at its next step; agents already running finish
$ aidlc autopilot tick
One pass in the foreground (debugging)
| Option | Description |
|---|---|
| --dry-run | Print what would be done; change nothing |
$ aidlc autopilot wait
Block until something new waits for you, the heartbeat passes, or the run ends, then exit
| Option | Description |
|---|---|
| --pending | Wait for a new pending entry (the one thing it waits for) |
| --heartbeat <minutes> | Exit after this many minutes with nothing new (default: "30") |
| --interval <seconds> | Seconds between checks (default: "15") |
$ aidlc claim <instance>
Claim a lifecycle instance for this session (writes sessions.ndjson)
| Option | Description |
|---|---|
| --renew | Renew an existing claim instead of taking a new one |
$ aidlc compliance [command]
Compliance packs — install, check, and report evidence per control
$ aidlc compliance add <pack>
Install a compliance pack into this project
$ aidlc compliance check
Check a change against the installed packs’ controls
| Option | Description |
|---|---|
| --diff <ref> | Assess the diff against this git ref instead of the working tree |
| --enforce | Exit non-zero on a failing or unassessed control |
| --json | Output machine-readable JSON |
$ aidlc compliance list
List available compliance packs and whether each is installed
| Option | Description |
|---|---|
| --json | Output machine-readable JSON |
$ aidlc compliance remove <pack>
Remove an installed compliance pack
$ aidlc compliance report
Evidence report: what each control requires and where the evidence is
| Option | Description |
|---|---|
| --instance <name> | Limit the report to one instance |
| --since <date> | Limit the report to instances completed on or after this date |
| --json | Output machine-readable JSON |
$ aidlc compliance upgrade <pack>
Upgrade an installed pack to the available version
$ aidlc constitution [command]
Import a product vision document and track the repo scope derived from it
$ aidlc constitution check
Report vision statements added or removed since the last import
| Option | Description |
|---|---|
| --json | Output machine-readable JSON |
| --exit-code | Exit 1 when drift is found (default: always exit 0) |
$ aidlc constitution import <path>
Read a vision document (.docx, .md, .markdown, .txt) into a snapshot
| Option | Description |
|---|---|
| --json | Output machine-readable JSON |
$ aidlc continue [instance]
Resume the active lifecycle instance from the next incomplete step
| Option | Description |
|---|---|
| --json | Output as JSON |
$ aidlc cost [command] [instance]
Per-instance cost tracking: reports, capture, rates, hooks
| Option | Description |
|---|---|
| --json | Structured JSON output |
| --by-template | Roll up average cost per template |
| --unattributed | List usage not attributed to any instance |
$ aidlc cost context
Resident context for this session, against the budget
| Option | Description |
|---|---|
| --json | Structured JSON output |
$ aidlc cost dedupe
Plan (or apply) the correction for usage counted once per content block
| Option | Description |
|---|---|
| --apply | Rewrite the ledgers — read-only without it |
| --json | Structured JSON output |
$ aidlc cost hooks [command]
Manage cost-capture hooks per platform
$ aidlc cost hooks install
Install cost-capture hooks
| Option | Description |
|---|---|
| --platform <name> | Limit to one platform (claude-code, kiro) |
$ aidlc cost hooks remove
Remove cost-capture hooks
| Option | Description |
|---|---|
| --platform <name> | Limit to one platform (claude-code, kiro) |
$ aidlc cost hooks status
Status cost-capture hooks
| Option | Description |
|---|---|
| --platform <name> | Limit to one platform (claude-code, kiro) |
$ aidlc cost providers [command]
Cost provider status
$ aidlc cost providers status
Show detection and metered-capture state per provider
$ aidlc cost rates [command]
Manage the usage→dollar rate table
$ aidlc cost rates show
Print the effective merged rate table
| Option | Description |
|---|---|
| --normalization | Print the model-id normalization rules |
$ aidlc cost rates update
Fetch current rates from the configured source
$ aidlc cost record
Record usage (hook mode via stdin, or --manual)
| Option | Description |
|---|---|
| --provider <name> | Cost provider (claude-code, kiro) |
| --detach | Spawn a background recorder and exit immediately |
| --session-end | The session has ended: drop its active-session stash entry |
| --manual | Manual entry mode (agent-driven fallback) |
| --instance <name> | Target instance (manual mode) |
| --session <id> | Session id, or "-" for none (manual mode) |
| --fidelity <f> | estimated | unknown (manual mode) |
| --units <json> | Units JSON (manual mode, estimated only) |
| --from <iso> | Coverage start (manual mode) |
| --to <iso> | Coverage end (manual mode) |
$ aidlc cost session-start
Stash a platform session id (hook mode via stdin)
| Option | Description |
|---|---|
| --provider <name> | Platform name |
$ aidlc cost sync [instance]
Reconcile historical platform records into ledgers
$ aidlc cross-check <instance>
Report where requirements, design and tasks disagree; writes nothing, blocks nothing
$ aidlc discover
Scan codebase, generate context documents, and seed the knowledge graph
| Option | Description |
|---|---|
| --json | Output full scan result as JSON |
| --no-knowledge | Skip seeding the knowledge graph |
| --force | Overwrite hand-edited context docs as well as generated ones |
$ aidlc docs
Generate onboarding documentation (.aidlc/ONBOARDING.md)
$ aidlc doctor
Check and repair repo hygiene (gitignore coverage, stale ephemera, tracked cost files)
| Option | Description |
|---|---|
| --dry-run | List pending migrations without applying anything |
| --yes | Apply index-mutating migrations without prompting |
$ aidlc explain [topic]
Explain why a part of AIDLC works the way it does (lists topics, or prints one)
$ aidlc gate <instance> [phase]
CI/CD gate check — exits 0 if phase is complete
| Option | Description |
|---|---|
| --json | Output structured JSON (GateCheckResult) |
| --verify | In verified mode, run verify.command when no matching passing test receipt exists |
$ aidlc hook [command]
Lifecycle hooks: session-start context and the opt-in phase guard
$ aidlc hook guard
Ask before code is edited during planning (PreToolUse hook mode)
$ aidlc hook install
Install the session-start hook (and, with --guard, the phase guard)
| Option | Description |
|---|---|
| --platform <name> | Platform to install for (claude-code, codex; default claude-code) |
| --guard | Also install the phase guard (Claude Code only; off by default) |
$ aidlc hook remove
Remove the lifecycle hooks, or only the phase guard with --guard
| Option | Description |
|---|---|
| --platform <name> | Limit to one platform (claude-code, codex) |
| --guard | Remove only the phase guard |
$ aidlc hook session-start
Print the claimed instance, its phase and next step (SessionStart hook mode)
$ aidlc init
Set up AIDLC: configure the project and install platform skills
| Option | Description |
|---|---|
| --platform <name> | Install skills for a single platform without prompts (claude-code, codex) |
| --non-interactive | Skip prompts, use defaults or existing config |
| --dry-run | Print what would be written without making changes |
| --no-cost-hooks | Skip installing cost-capture hooks |
| --no-lifecycle-hooks | Skip installing the session-start hook (and the Codex question) |
| --autopilot | Also set up autopilot (agent, parallelism, cost cap, where it stops for you, release step) |
| --host <name> | Where the repository is hosted: github, gitlab or git (detected from origin when omitted) |
$ aidlc knowledge [command]
Local knowledge graph — persistent codebase memory for agents
$ aidlc knowledge add
Add an entity (via flags, or stdin YAML with --stdin)
| Option | Description |
|---|---|
| --id <id> | Entity id (lowercase slug) |
| --type <type> | Entity type (module, service, decision, … or custom:<name>) |
| --name <name> | Human-readable name |
| --description <text> | Free-text description |
| --confidence <n> | Confidence 0.0–1.0 |
| --source <path> | Source file path or "agent-inferred" |
| --tags <tags> | Comma-separated tags |
| --stdin | Read one or more entity YAML documents from stdin |
$ aidlc knowledge compact
Deduplicate and normalize YAML source files (rewrites files)
$ aidlc knowledge context
Generate a markdown context summary for agent prompts
| Option | Description |
|---|---|
| --scope <scope> | full | phase <name> | file <path> (default: "full") |
| --phase <name> | Lifecycle phase (with --scope phase) |
| --file <path> | File path (with --scope file) |
| --max-tokens <n> | Token budget (default: 2000) |
| --include-stale | Include low-confidence entities |
$ aidlc knowledge get <id>
Get a single entity with all its relationships
| Option | Description |
|---|---|
| --format <fmt> | Output format: yaml or json (default: "yaml") |
$ aidlc knowledge graph <id>
Subgraph of entities within N hops
| Option | Description |
|---|---|
| --depth <n> | Traversal depth (default: 1) |
| --format <fmt> | Output format: yaml or json (default: "yaml") |
$ aidlc knowledge import <file>
Bulk import entities and relationships from a YAML file
$ aidlc knowledge install-merge-driver
Install the git merge driver for knowledge YAML files (writes git config)
| Option | Description |
|---|---|
| --yes | Skip the confirmation prompt (CI) |
$ aidlc knowledge query <term>
Full-text search across the graph
| Option | Description |
|---|---|
| --type <type> | Filter by entity type |
| --min-confidence <n> | Minimum confidence |
| --limit <n> | Maximum results (default: 20) |
| --format <fmt> | Output format: yaml or json (default: "yaml") |
$ aidlc knowledge rebuild
Rebuild the SQLite index from YAML sources
$ aidlc knowledge relate
Create a relationship between two existing entities
| Option | Description |
|---|---|
| --from <id> | Source entity id |
| --to <id> | Target entity id |
| --type <type> | Relationship type (depends-on, uses, … or custom:<name>) |
$ aidlc knowledge stale
List entities that may no longer reflect the code
| Option | Description |
|---|---|
| --days <n> | Age threshold in days (default: 30) |
| --check-git | Also degrade confidence of entities whose source files changed |
| --format <fmt> | Output format: yaml or json (default: "yaml") |
$ aidlc knowledge sync
After git pull: rebuild the index and report suspicious merges
| Option | Description |
|---|---|
| --format <fmt> | Output format: yaml or json (default: "yaml") |
$ aidlc knowledge update <id>
Update fields on an existing entity
| Option | Description |
|---|---|
| --description <text> | New description |
| --confidence <n> | New confidence 0.0–1.0 |
| --tags <tags> | Comma-separated tags (replaces existing) |
| --name <name> | New name |
$ aidlc knowledge verify <id>
Confirm an entity is still accurate (bumps lastVerified and confidence)
$ aidlc menu
Open the aidlc console (also: run `aidlc` with no arguments)
$ aidlc metrics
DORA-style metrics: change failure rate, lead times, true cost
| Option | Description |
|---|---|
| --json | Output machine-readable JSON |
$ aidlc release <instance>
Release a claimed instance (writes sessions.ndjson)
$ aidlc revert <instance>
Undo a task's commits (found by their Task: trailer) after showing the plan
| Option | Description |
|---|---|
| --task <id> | Task to undo, e.g. T3 |
| --phase <phase> | Undo every task commit of the phase (implementation only) |
| --dry-run | Print the plan; change nothing |
| --yes | Revert without asking (needed without a terminal) |
| --override | Revert without a live claim on the instance |
$ aidlc review <instance> <artifact>
Run an adversarial review of a lifecycle artifact, recording structured findings
| Option | Description |
|---|---|
| --json | Output findings as structured JSON |
$ aidlc roadmap [command]
Project the roadmap onto GitHub Issues, import an issue, pick or rank the next item, park one, see its milestones, or view it as a page
$ aidlc roadmap assign-milestones
List open items with no milestone, or write the milestone of each item named by --set (commits nothing)
| Option | Description |
|---|---|
| --set <item=milestone> | Write this item's milestone: line (a milestone id or none); repeatable (default: []) |
$ aidlc roadmap board-workflow
Print the GitHub Actions workflow that moves a Project board from roadmap labels
$ aidlc roadmap import <issue-url>
Seed one inbox roadmap item from a GitHub issue (one-shot)
$ aidlc roadmap next
Name the next ready backlog item: lowest priority whose dependencies are done (read-only)
| Option | Description |
|---|---|
| --json | Print {next, skipped} as JSON |
| --explain | Also list the ready order and every skipped item with its reason |
| --autopilot | Pick as autopilot does: leave out items marked run: attended |
$ aidlc roadmap park [instance]
Park in hold/ the item promoted to an instance, or the one named by --item
| Option | Description |
|---|---|
| --item <item> | Park this open item (file name or id) instead, whatever its promoted_to |
| --reason <text> | Why it is parked; recorded in the item history |
$ aidlc roadmap rank <item> <rank>
Give a backlog item a rank and renumber the others so ranks stay unique and gap-free
| Option | Description |
|---|---|
| --dry-run | Print the resulting order and write nothing |
$ aidlc roadmap status
Print each milestone and what is done, in flight, next, parked and open under it, then Unassigned
| Option | Description |
|---|---|
| --milestone <id> | Print only this milestone, or none for Unassigned |
$ aidlc roadmap sync
Project eligible roadmap items onto GitHub Issues (one-way)
| Option | Description |
|---|---|
| --dry-run | Print the plan and write nothing |
| --yes | Apply the plan without asking |
| --repo <owner/name> | Target repository (overrides roadmap.sync.repo) |
| --retire-ineligible | Close issues whose item has left a projected status |
$ aidlc roadmap triage <item> <to>
Move an inbox item to backlog (with its rank and run mode), or park or decline it in hold/
| Option | Description |
|---|---|
| --rank <n> | With backlog: rank to give it, as `aidlc roadmap rank` does |
| --run <mode> | With backlog: autopilot or attended, written to its run: line |
| --reason <text> | With park or decline: why; recorded in the item history |
$ aidlc roadmap view|graph
Write the roadmap as one HTML page (board and dependency map) and open it
| Option | Description |
|---|---|
| --no-open | Write the page without opening a browser |
| --out <path> | Write the page here instead of <git-common-dir>/aidlc/roadmap.html |
$ aidlc spec [command]
Read the spec corpus — what the system does today — and fold changes into it
$ aidlc spec fold <instance>
Fold an instance's ## Spec delta into the corpus (also run at completion)
| Option | Description |
|---|---|
| --dry-run | Report what the fold would do; write nothing |
| --json | Output machine-readable JSON |
$ aidlc spec show [capability]
List capabilities, or print one capability's requirements and revisions
| Option | Description |
|---|---|
| --json | Output machine-readable JSON |
$ aidlc start [template]
Begin a new lifecycle instance
| Option | Description |
|---|---|
| --name <instance-name> | Instance name (URL-safe) |
| --scope <scope> | Cycle scope (full, standard, micro) |
| --non-interactive | Disable interactive prompts (for AI agents) |
| --worktree | Create the instance in a new git worktree (branch based on main) |
| --no-code | Start without a branch; implementation entry stays blocked until one exists |
| --no-open | With --worktree inside herdr, do not open a herdr workspace or start the agent there |
| --roadmap-item <item> | Link a backlog or inbox roadmap item (file name or id): set promoted_to, move it to in-progress, seed the instance |
$ aidlc status
Show progress across active lifecycle instances
| Option | Description |
|---|---|
| --json | Output in JSON format for machine consumption |
| --all | Include instances from all local branches |
| --prune | Remove stale registry entries and orphaned claims (explicit cleanup) |
$ aidlc templates [command]
Workflow templates — their phases and the artifacts each phase requires
$ aidlc templates list
List available templates
| Option | Description |
|---|---|
| --json | Output as JSON |
$ aidlc templates show <name>
Show a template's phases and their required artifacts
| Option | Description |
|---|---|
| --scope <scope> | Restrict to the phases this scope runs (full, standard, micro) |
| --json | Output as JSON |
$ aidlc transition <instance>
Evaluate gates and advance to the next phase
| Option | Description |
|---|---|
| --override | Override ownership gate |
| --json | Output result as JSON |
$ aidlc update
Update the AIDLC CLI and refresh project skills
| Option | Description |
|---|---|
| --self-only | Only update the CLI globally, skip project file refresh |
| --project-only | Only refresh project files from the currently installed CLI |
| --rediscover | Also regenerate context docs in .aidlc/context/ |
| --dry-run | Show what would change without writing anything |
$ aidlc verify <instance>
Run the project's test command (verify.command) and write the instance's receipt