CLI · v1.4.4

Command Reference

Every ai command runs against ~/.ai/ by default. Set AI_ROOT=/path/to/dir to redirect to a different directory — useful for testing without touching your live constitution.

Setup & Configuration

`ai setup`

One command to go from nothing to fully governed. Runs the guided TUI wizard, then automatically:

Generates Constitution.md and Constitution.compact.md
Installs 13 governance hooks from ai-atoms.com
Installs git/gh command-wrappers for your OS
Wires Claude Code, Copilot, Cursor, or Codex based on your selections
Installs Claude official plugins (security-guidance, superpowers…)

ai setup                        # interactive TUI (recommended)
ai setup --non-interactive      # use seeded answers
ai setup --no-hooks             # generate constitution only — skip wiring

All clients receive Constitution.compact.md (~8 KB) not the full 42 KB source — same operative rules, 80% fewer tokens per session.

`ai compress`

Generates Constitution.compact.md from the full Constitution.md. Run after amending your constitution.

ai compress                         # regenerate compact form
ai compress --wire                  # regenerate + activate in Claude Code
ai compress --check-coverage        # verify compact contains all rule IDs
ai compress --personas              # extract per-persona YAML derivatives
ai compress --check                 # detect stale persona derivatives

`ai doctor [--fix]`

Health check on the constitution tree. Detects and optionally repairs common problems:

Python App Execution Alias stubs on Windows (--fix removes them)
Missing Constitution.compact.md (--fix generates it)
CLAUDE.md wired to full constitution instead of compact (--fix updates it)
Blocking wrapper hooks not installed on disk
Hook wiring completeness in settings.json

ai doctor           # report issues
ai doctor --fix     # report + auto-repair where safe

`ai wrap <tool> [-- args…]`

Cross-platform governance dispatcher invoked by the git/gh shims in ~/.ai/bin/. Not called directly by users. Loads command-wrappers.toml, runs pre-hooks (branch-guard, secret-precommit, no-verify-strip…), execs the real binary, runs post-hooks. Blocking hooks fail closed when not installed.

`ai status`

Prints AI root path, constitution file presence, hook status, memory count, and recent audit activity.

ai status

Constitution Lifecycle

`ai constitution backup [--clear-links]`

Archives all of ~/.ai/ to ~/.config/aiConstitution/backups/<timestamp>.tar.gz.

ai constitution backup                # full archive
ai constitution backup --clear-links  # archive + clear tool wiring

`ai constitution restore [backup-id | --url <git-url>]`

Removes current ~/.ai/ and restores from a backup or remote git repo.

ai constitution restore
ai constitution restore 20260529T120000Z
ai constitution restore --url https://github.com/you/ai.git

`ai migrate`

Migrates a legacy four-file layout to unified Constitution.md.

ai migrate --flatten           # merge four files → one Constitution.md
ai migrate --add-behavioral    # insert §2 Behavioral Standards
ai migrate --generate-runtime  # write Constitution.compact.md

`ai init-integrate [--cursor] [--codex]`

Wire AI tool integrations into the current project directory. Run once per repo for Cursor and Codex — Claude Code and Copilot are wired globally by ai setup.

ai init-integrate --cursor    # .cursor/rules/constitution.md → Constitution.compact.md
ai init-integrate --codex     # write/update AGENTS.md with @-include

Amendments

The amendment lifecycle: violation → draft stub → human edit → apply → re-compress.

`ai amend draft <violation-file>`

ai amend draft ~/.ai/audit/violations/20260529T120000Z-worktree.md

`ai amend apply <draft>`

ai amend apply ~/.ai/governance/plans/20260529T120000Z-worktree.md

`ai amend list` / `ai amend show <slug>`

ai amend list
ai amend show worktree-slug

`ai review --check`

4-scan governance review: violations, overrides, drift, dead rules.

ai review --check

Hooks

`ai hooks install`

Fetch and install hooks from ai-atoms.com. Called automatically by ai setup.

ai hooks install --all              # all catalog hooks + infrastructure
ai hooks install secret-precommit  # specific hook
ai hooks install command-wrappers  # git/gh/notify-me shims for your OS

On Windows, command-wrappers installs git.cmd, git.ps1, gh.cmd, gh.ps1.

`ai hooks run <slug> [--self-check]`

Portable cross-platform hook invocation. Auto-discovers python3/python/py -3 on Windows.

ai hooks run branch-guard
ai hooks run secret-precommit --self-check   # validate hook loads correctly

`ai hooks available` / `ai hooks list`

ai hooks available    # browse installable hooks from ai-atoms.com
ai hooks list         # installed hooks + per-client wiring status

`ai hooks validate` / `ai hooks evaluate`

ai hooks validate   # lint hook scripts
ai hooks evaluate   # run each hook with synthetic event; assert non-crash

Skills & Plugins

`ai skills`

ai skills available              # browse 280+ skills from ai-atoms.com
ai skills available -p           # interactive checkbox picker — select & install
ai skills install <slug>         # install; auto-installs sub-skills
ai skills link                   # symlink installed skills to ~/.claude/skills/
ai skills list                   # installed skills + descriptions
ai skills show <name>            # cat a skill's SKILL.md
ai skills validate               # check each skill dir has valid SKILL.md

ai skills available -p opens a scrollable checkbox TUI: Space toggles, a selects all, Enter installs, ↑↓/jk navigate, Ctrl+d/u page.

`ai plugins`

ai plugins install <name[@version]>  # install from plugin-atoms.com
ai plugins status                     # list installed plugins
ai plugins enable / disable <name>   # manage active set

Claude official plugins are installed automatically by ai setup when Claude Code is selected: security-guidance, superpowers, plus any you pick in the wizard (amendment-author, hook-author…).

`ai op` — 1Password integration

ai op env                    # print KEY=op://vault/item/field lines
ai op signin / signout / whoami
ai op clip <op://ref>       # copy secret to clipboard — never prints value

Identity & Mode

ai clone <url> [--identity <name>]   # git clone + identity routing
ai profile list/show/new/edit/remove  # manage persona profiles
ai persona list / show <name>         # installed personas
ai mode list / current / clear        # inspect and clear active mode
ai pm-mode                            # activate plan-first discipline
ai spawn <persona>                   # activate a sub-persona

Portability

ai backup                    # snapshot ~/.ai/ to backups/
ai sync push / pull          # push/pull ~/.ai/ to configured git remote
ai restore <snapshot>       # restore from snapshot
ai init                      # scaffold project.yaml + AI tool integration files

Audit & Governance

ai audit override --section "§3.2" --scope session \
  --strict "would have blocked" --relaxed "allowed once" \
  --risk "minimal" --confirmation "yes"

ai audit violation --section "§3.1.P2" \
  --what "..." --noticed self-detected --remediation "corrected"

ai issue file --title "Bug: X" --type finding
ai memory retire user_role

Full flag reference

ai --help
ai setup --help
ai compress --help
ai doctor --help
ai wrap --help
ai skills available --help

Command Reference

Setup & Configuration

ai setup

ai compress

ai doctor [--fix]

ai wrap <tool> [-- args…]

ai status

Constitution Lifecycle

ai constitution backup [--clear-links]

ai constitution restore [backup-id | --url <git-url>]

ai migrate

ai init-integrate [--cursor] [--codex]