CLI reference

Run via npx @ambystech/ambykit <command> or install globally and use ambykit <command>.

Global flags

• --verbose — detailed logging.
• --dry-run — show what would change without writing files.
• --yes — assume yes for prompts; skips interactive tool selection.

Output adapts to your terminal — color + glyphs when interactive, plain text when piped or under NO_COLOR, ASCII fallback where glyphs are unsupported, and byte-stable --json.

ambykit init [dir]

ambykit init [dir] [--tools=claude,…] [--yes] [--dry-run]

Scaffold AmbyKit into a project: creates .amby/ (constitution + config.json), detects installed assistants, emits their native files, and writes the shared AGENTS.md (+ CLAUDE.md bridge for Claude). With no --tools on an interactive terminal it opens a tool picker.

Brownfield-safe. init detects an existing project (a rules file, source files, or git history) and merges rather than overwrites: existing CLAUDE.md/AGENTS.md content is preserved and only AmbyKit’s ### AmbyKit usage section is added/updated. The file is backed up to .amby/backups/ first, a section you hand-edited is left untouched, and --dry-run previews the change.

ambykit add <tool…>

ambykit add <tool…> [--dry-run]

Add or refresh one or more targets (see tool compatibility). With no target on a TTY it opens a multi-select picker; non-interactively it errors with the available targets.

ambykit sync

ambykit sync [--check] [--include-user] [--dry-run]

Re-emit all configured tools from the neutral source. --check exits non-zero if anything is out of date (used in CI). User-level MCP files are opt-in via --include-user. sync is also the update path for existing docs — it merges AmbyKit’s section into each tool’s rules file non-destructively (preserve, back up, skip hand-edits), keeping your agent docs current.

ambykit dashboard [story-id]

ambykit dashboard [story-id] [--interactive] [--json] [--status=X] [--feature=X]

Progress view over the story/task graph, computed locally from specs/*/spec.md + tasks.md (zero model tokens). --interactive opens a full-screen navigable view on a TTY.

ambykit analyze

ambykit analyze [--json]

Cross-check spec ↔ plan ↔ tasks for coverage, consistency, and dependency-graph health. Read-only.

ambykit check

ambykit check

Validate the project’s AmbyKit setup and configuration.

Also reports stale worktrees and role problems in .amby/roles/ (oversized, duplicate ids, deleted defaults). ambykit sync validates roles the same way and emits one native sub-agent per role for Claude Code, OpenCode, and Copilot.

ambykit restore [file]

ambykit restore [file]   # no file → list available backups

Recover an agent-doc file (AGENTS.md, CLAUDE.md, …) from the timestamped backup AmbyKit writes to .amby/backups/ before it modifies an existing file. With no argument it lists what can be restored.

ambykit worktree

ambykit worktree <feature>          # create .worktrees/<feature> on branch <feature>
ambykit worktree list               # feature, branch, clean/dirty/merged, path
ambykit worktree remove <feature>   # delete the working copy; branch is kept (--force if dirty)

Per-feature git worktrees for parallel work without checkout switching. Worktrees live at .worktrees/<feature>/ (gitignored); new branches start from the default branch. Enable automatic creation from /amby.specify at ambykit init or with "worktrees": true in .amby/config.json.

ambykit update

ambykit update

Update the AmbyKit CLI to the latest published version when it’s behind, then — on a re-run once current — refresh this project’s tool prompts. When outdated it upgrades the CLI and asks you to re-run ambykit update to refresh prompts under the new version; if it can’t self-update (e.g. an npx run or a permissions error) it prints the exact npm install -g command.