BA-kit CLI

Supported customer installer for BA-kit on Claude Code, Codex CLI, and Antigravity IDE.

Install

npm install -g @bakit-org/cli@^1.4.0
ba-kit install
ba-kit doctor

CLI 1.4.0 supports BA-kit runtime payload schema 2 and maintains canonical schema-v3 state. Omit --runtime to install Claude Code only; select one or more runtimes explicitly when needed:

ba-kit install --runtime claude,codex,agy
ba-kit update
ba-kit doctor
ba-kit version
ba-kit uninstall --runtime codex,agy

There is no --product flag. Product selection is access-driven:

• Without GitHub authentication, public Solo Basic is selected automatically.
• With GitHub authentication, the CLI shows the products available to the account.

Runtime Scope

| Key | Runtime | Standard profile | | --- | --- | --- | | claude | Claude Code | Native skills, agents, hooks, rules, templates, contract, guardrails | | codex | Codex CLI | Native generated skills, registered agents/hooks, templates, contract, guardrails | | agy | Antigravity | Native skills plus managed Knowledge Item and role/handoff profiles; hybrid enforcement |

Antigravity always provisions ~/.gemini/antigravity as the canonical support root, then also installs into detected ~/.gemini/antigravity-cli and ~/.gemini/antigravity-ide homes. Its interactive runtime does not expose a deterministic headless hook surface, so preflight/audit enforcement remains wrapper/operator-driven.

The standard payload includes the four canonical delegated roles: ba-researcher, ba-documentation-agent, ux-designer, and independent read-only ba-reviewer. A producer cannot approve its own work. Required review receipts are bound to source hashes, and missing or stale receipts block compilation/package promotion.

Solo Basic Scope

Solo Basic installs exactly five skills (ba-start, ba-do, ba-next, ba-impact, brainstorm) plus templates and core contract content. It does not install standard-profile agents, hooks, scripts, settings, framework files, pip packages, or tool lanes.

Prerequisites

• Node.js 18+.
• Public Solo Basic: jq and curl.
• Private products: GitHub CLI (gh) authenticated with gh auth login.
• Windows: Git for Windows, which provides bash.exe.

State, Transactions, And Recovery

Canonical state is stored at:

~/.local/share/ba-kit/runtime-state/{runtime}/state.json

Schema-v3 state records the payload schema, product/profile/version, runtime targets, registrations, managed hashes, and preserved-file status. Legacy and schema-v2 installs migrate forward during install/update.

Install, update, and uninstall are transactional across selected runtimes. Journals live under ~/.local/share/ba-kit/transactions/; an interrupted transaction is recovered before a later mutation. Malformed journals or state fail closed. ba-kit doctor is read-only and reports the recovery issue.

Files are removed or replaced only while their hashes still match BA-kit-managed content. User-modified and retired files are preserved as preserved-modified. Uninstall may leave an uninstalled-with-preserved-files tombstone so a later reinstall does not misclassify those files.

Runtime assets and metadata files are checked against approved runtime roots after realpath resolution. Symlinked parents/files that escape those roots fail closed before mutation.

RECOVERY_REQUIRED.json prevents an older CLI from mutating a schema-v3 installation. Do not delete the barrier. Upgrade the npm CLI and run:

ba-kit doctor
ba-kit update
ba-kit doctor

Doctor checks schema-v3 state, managed path containment and hashes, transaction health, native Reviewer/orchestration capabilities, and Claude/Codex registrations. Repair uses ba-kit update after any malformed external configuration is corrected.

Trust Boundary

The CLI validates the release manifest, runtime component contract, and extracted file hashes before mutation. GitHub release checksums protect download integrity under GitHub TLS and release-authority trust; they are not an independent publisher signature. Install only the official @bakit-org/cli package and releases from the bakit-org GitHub organization.

Release Compatibility

BA-kit archives with runtime_payload_schema: 2 require CLI 1.4.0 or newer. Release order is CLI first, then the BA-kit archive. npm publishing, Git tags, GitHub Releases, and rollout require explicit maintainer authorization.

Never downgrade schema-v3 state in place. If a release must be rolled back, use transaction recovery or a forward CLI/BA-kit patch and keep project artifacts plus review receipts unchanged.

Quick Start

Public Solo Basic

npm install -g @bakit-org/cli@^1.4.0
ba-kit install
ba-kit doctor

Private Products

1. Accept the product's GitHub organization invitation.
2. Install and authenticate GitHub CLI with gh auth login.
3. Install @bakit-org/cli 1.4.0 or newer.
4. Run ba-kit install --runtime <runtime-list>.
5. Run ba-kit doctor before starting /ba-start or /ba-do.