$ aidlc — CLI Reference
Generated from the shipped CLI (23 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 add skill publish-post --description "Publish a new MDX post" \ --steps "1. Create the file... | 2. Update the index..." |
| aidlc add skill --re-emit | Re-package every operational skill |
| aidlc add skill publish-post --check | Verify one skill |
$ 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 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 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
| Option | Description |
|---|---|
| --dry-run | List pending migrations without applying anything |
| --yes | Apply index-mutating migrations without prompting |
| aidlc doctor | Apply safe migrations; confirm before index changes |
| aidlc doctor --dry-run | Preview what would change |
| aidlc doctor --yes | Also apply index changes without prompting (CI) |
| 0 | everything healthy or applied |
| 1 | confirm-tier work remains pending (declined, non-interactive, or blocked by staged changes) or a migration failed |
$ aidlc gate <instance> [phase]
CI/CD gate check — exits 0 if phase is complete
| Option | Description |
|---|---|
| --json | Output structured JSON (GateCheckResult) |
$ 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, copilot, cursor, kiro, windsurf) |
| --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 |
$ 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
Interactive menu of common commands (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 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, or import an issue
$ aidlc roadmap import <issue-url>
Seed one inbox roadmap item from a GitHub issue (one-shot)
$ 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 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 |
$ 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 update | Update CLI + refresh project skills |
| aidlc update --self-only | Just update the global CLI package |
| aidlc update --project-only | Just refresh .kiro/skills/ from current CLI |
| aidlc update --rediscover | Also regenerate .aidlc/context/ docs |
| aidlc update --dry-run | Preview changes without applying them |
| 1. Detects your package manager (npm, pnpm, yarn, bun) | |
| 2. Checks the npm registry for a newer version | |
| 3. Updates the CLI if a newer version is available | |
| 4. Re-runs the install plan for each configured platform to refresh skill shims and steering files | |
| 5. Skips .aidlc/context/ docs unless --rediscover is passed (context docs may have been manually edited) |