How to run the CLI locally

Purpose #

Recipes for running aidokit from your local checkout against a scratch directory, with the flags that show up most often.

Pre-flight #

pnpm install
pnpm build

The CLI binary lives at packages/cli/dist/bin/aidokit.js. Invoke via node (no global install required during development).

Common recipes #

Default greenfield Node-TS #

mkdir /tmp/scratch && cd /tmp/scratch && git init
node ~/aidokit/packages/cli/dist/bin/aidokit.js init \
  --adapter claude-code --conformance standard --stack node-ts --yes

Interactive (no flags) #

node ~/aidokit/packages/cli/dist/bin/aidokit.js init

Walks you through every selection. Useful for exercising the @clack/prompts UI.

Dry run (no writes) #

node ~/aidokit/packages/cli/dist/bin/aidokit.js init \
  --adapter claude-code --stack node-ts --yes --dry-run

Prints the file plan; exits 0; nothing written.

Skip Beads or MCP install #

node ~/aidokit/packages/cli/dist/bin/aidokit.js init --no-beads --no-mcp ...

JSON output (for scripting) #

node ~/aidokit/packages/cli/dist/bin/aidokit.js init --json ...

Implies --no-color and --no-prompts. Single JSON object on stdout; progress on stderr.

Verbose #

node ~/aidokit/packages/cli/dist/bin/aidokit.js init --verbose ...

Adds step timestamps. Combined with --json, adds a steps array.

Multi-adapter (v1.0) #

node ~/aidokit/packages/cli/dist/bin/aidokit.js init \
  --adapter claude-code,codex,copilot \
  --stack node-ts --yes

Emits three engine directories; shared docs/ + agent-artifacts/ written once.

Doctor #

cd /path/to/an-initialized-project
node ~/aidokit/packages/cli/dist/bin/aidokit.js doctor [--strict] [--fix-hints]

Read-only. Exit 13 on any MUST failure.

Sync (re-emit adapter-owned files only) #

node ~/aidokit/packages/cli/dist/bin/aidokit.js sync --dry-run
node ~/aidokit/packages/cli/dist/bin/aidokit.js sync --scripts

Never touches docs/specs/**, agent-artifacts/**, CHANGELOG.md, or Beads DB.

MCP management #

node ~/aidokit/packages/cli/dist/bin/aidokit.js mcp list
node ~/aidokit/packages/cli/dist/bin/aidokit.js mcp add context7
node ~/aidokit/packages/cli/dist/bin/aidokit.js mcp add filesystem    # sensitive — explicit confirm even with --yes
node ~/aidokit/packages/cli/dist/bin/aidokit.js mcp remove context7
node ~/aidokit/packages/cli/dist/bin/aidokit.js mcp scope context7 --add-role researcher
node ~/aidokit/packages/cli/dist/bin/aidokit.js mcp suggest

A shell alias for development #

Put this in your shell rc:

alias aido-dev='node ~/aidokit/packages/cli/dist/bin/aidokit.js'

Then: aido-dev init --adapter claude-code --stack node-ts --yes.

Common pitfalls #

Building before running. dist/bin/aidokit.js doesn't exist until pnpm build. Run it once; Turborepo caches subsequent builds.
Running from the repo root. Don't. aidokit init would mutate this repo's .claude/ and break dogfood. Always use a scratch dir.
Forgetting git init in the scratch dir. Some flows (Beads, git remote detection) expect a git repo.
--yes bypassing safety prompts. It doesn't bypass securitySensitive MCPs (Filesystem, graphify) or prereq installs (ADR-0008).
Expecting npx aidokit to work pre-v1.0. latest dist-tag is unset; you'd need npx aidokit@alpha once published. Locally, just call node packages/cli/dist/bin/aidokit.js.