CLI reference

Every command, flag, environment variable, and configuration file aidokit exposes.

Synopsis

shell

aidokit <command> [<subcommand>] [<args>] [--flag] [--flag=value]

Global flags

Work with every command.

Flag	Short	Default	Description
`--help`	`-h`	false	Print help and exit 0.
`--version`	`-v`	false	Print CLI version and exit 0.
`--yes`	`-y`	false	Accept prompts with defaults. Does NOT bypass security-sensitive prompts or prereq installs.
`--no-prompts`	—	false	Disable interactive prompts; fail if input is required.
`--dry-run`	—	false	Show what would happen; no writes, no shell.
`--json`	—	false	Emit a single JSON object on stdout. Implies `--no-color` and `--no-prompts`.
`--verbose`	—	false	Print detailed 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.
`--skip-prereq-check`	—	false	Bypass prereq detection. Use when you know your environment is set up.

--verbose and --quiet are mutually exclusive (exit 2).

aidokit init

synopsis

aidokit init [--adapter <name>] [--conformance <level>] [--brownfield]
          [--stack <ids>] [--no-beads] [--no-mcp]
          [--source-docs <path>] [--dry-run] [--yes]

Bootstrap a project with the AI Dev Orchestrator workflow.

Flag	Default	Description
`--adapter <name>`	prompt	One of `claude-code`, `codex`, `copilot`, or a comma-separated list for multi-adapter.
`--conformance <level>`	`standard`	`minimum`, `standard`, or `strict`.
`--brownfield`	false	Scan for existing PRD/BRD/code; offer to ingest.
`--stack <id1,id2,…>`	auto-detect	Force specific stack packs.
`--no-beads`	false	Skip Beads initialisation.
`--no-mcp`	false	Skip MCP installation.
`--source-docs <path>`	prompt	Brownfield only: where existing source docs live.

Exit codes: 0, 1, 2, 10, 11, 12, 13, 20, 21, 40.

aidokit doctor

synopsis

aidokit doctor [--fix-hints] [--strict]

Read-only health check. Verifies prereqs, adapter installation, file presence, MCP scoping, conformance snapshot. Never writes.

Flag	Default	Description
`--fix-hints`	true	Include suggested fixes in output.
`--strict`	false	Treat warnings as failures (exit 1 on any warning).

Exit codes: 0 (all pass), 1 (any check failed), 13 (conformance fail).

aidokit sync

synopsis

aidokit sync [--scripts] [--skills] [--agents] [--dry-run] [--yes]

Re-emit adapter-owned files from the current adapter package. Shows a diff before writing; never overwrites user-owned files without confirmation.

Flag	Effect
`--scripts`	Sync only hook scripts.
`--skills`	Sync only skills.
`--agents`	Sync only role files.

aidokit validate

synopsis

aidokit validate <artifact-path> [--schema <name>]

Validate an artifact (task brief, change summary, test report, …) against its JSON schema from @aidokit/core.

--schema values: task-brief, change-summary, test-report, maintenance-report, blocker, digest-report, delta-spec.

aidokit migrate

synopsis

aidokit migrate <from>-to-<to> [--backup-dir <path>] [--review]

Run a registered migration script. Backs up affected files before changes. Currently shipped: v3-to-v4.

aidokit mcp

Subcommand	Description
`aidokit mcp list [--scoped-to <role>]`	List installed MCPs with role scoping.
`aidokit mcp add <id> [--roles <list>] [--custom-url <url>]`	Install an MCP from the catalog or via custom URL.
`aidokit mcp remove <id>`	Uninstall an MCP and strip role frontmatter.
`aidokit mcp scope <id> --add-role <name> / --remove-role <name> / --set-roles <list>`	Change which roles see an installed MCP.
`aidokit mcp suggest`	Re-run trigger eval; print MCPs that would be suggested but aren't installed.

See MCP catalog for entries and trigger grammar.

aidokit skills

Subcommand	Description
`aidokit skills list [--source <core\|stack-pack\|personal>]`	List skills in the project's engine directory.
`aidokit skills add <id> [--from <source>]`	Add a skill from the core base set or a stack pack.
`aidokit skills personal init`	Create `$AIDO_HOME/personal-skills/`.
`aidokit skills personal add <name>`	Scaffold a new personal skill.
`aidokit skills personal list`	List personal skills.

aidokit new

Subcommand	Description
`aidokit new task <slug> [--phase <n>] [--scope <files>]`	Create a task brief. With Beads enabled, runs `bd create`.
`aidokit new adr <slug>`	Create the next-numbered ADR.
`aidokit new skill <name> [--triggers <globs>] [--roles <roles>]`	Scaffold a skill file.
`aidokit new capability <slug>`	Create `docs/specs/<slug>/spec.md` + `spec-summary.md`.

aidokit manifest

synopsis

aidokit manifest [--json]

Print the project's .aido/adapter.md manifest.

aidokit add adapter (v1.0)

synopsis

aidokit add adapter <name> [--conformance <level>]

Add a second adapter to an existing project. Shared docs/ and agent-artifacts/ are preserved.

aidokit remove adapter (v1.0)

synopsis

aidokit remove adapter <name> [--keep-shared]

Remove an adapter. Shared docs preserved by default.

aidokit search (v1.0)

Subcommand	Description
`aidokit search adapter [<query>] [--verified-only]`	npm-native discovery of adapter packages.
`aidokit search stack-pack [<query>] [--verified-only]`	npm-native discovery of stack-pack packages.

aidokit list

Subcommand	Description
`aidokit list adapters`	List adapter packages installed locally.
`aidokit list stack-packs`	List stack-pack packages installed locally.

Environment variables

Variable	Purpose
`AIDO_HOME`	Override default location of personal config (default `~/.aido/`).
`AIDO_LOG_LEVEL`	`error` / `warn` / `info` / `debug` / `trace`.
`AIDO_NO_UPDATE_CHECK`	If set to `1`, skip checking for newer aidokit versions.
`AIDO_OFFLINE`	If `1`, refuse any network operation.
`NO_COLOR`	Standard convention; disables colour.
`CI`	Defaults change in CI envs: `--no-prompts` implied, `--yes` honoured.
`DEBUG`	Standard debug namespace (`aidokit:*`).

Configuration files

Path	Owner	Purpose
`<project>/.aido/adapter.md`	CLI	Records adapter, version, conformance, spec version.
`<project>/.aido/state.json`	CLI	Selected MCPs, sync history, audit log.
`<project>/.aido-staging/`	CLI	Transient staging directory; auto-cleaned on success.
`~/.aido/config.json`	User	Preferences (default adapter, etc.).
`~/.aido/personal-skills/`	User	Cross-project skills.

--json output shape

Success:

json

{
  "ok": true,
  "command": "init",
  "result": {
    "adapter": "claude-code",
    "conformance": "standard",
    "filesWritten": 47,
    "mcpsInstalled": 3,
    "nextSteps": ["claude", "/intake \"describe your project\""]
  }
}

Error:

json

{
  "ok": false,
  "command": "init",
  "error": {
    "code": "PREREQ_MISSING",
    "exitCode": 10,
    "message": "Prerequisite missing: Claude Code",
    "details": { "prereq": "claude-code", "minVersion": "2.1.32" },
    "hint": "Install Claude Code via: curl -fsSL claude.ai/install.sh | bash"
  }
}

See Exit codes for the full code ↔ exit-code map.