CLI & Subcommands

This page is the command reference for the aid CLI. For full installation and bootstrapping instructions, see the Installation guide.

Command surface

aid                              Show the text status screen (project state + update notice)
aid -h | --help                  Show help
aid version                      Print the CLI version
aid status                       Show AID state of the current project
aid add <tool>[,...]             Add tool(s): claude-code, codex, cursor, copilot-cli, antigravity
aid update [<tool>... | self]    Update to latest; no arg = all installed tools; 'self' = the aid CLI
aid remove [<tool>... | self]    Remove; no arg = ALL AID from the project (asks to confirm); 'self' = the aid CLI
aid dashboard start|stop ...     Start/stop the local web dashboard
aid projects [list|add|remove|scan]
                                 List, register, unregister, or scan for AID projects
aid chat <verb> ...              Talk to another AI coding session (see below)
aid <command> -h | --help        Per-command help

Bare aid vs aid dashboard start

Running aid (no arguments) shows the text status screen — a terminal summary for the current project. The web dashboard is a separate, browser-based UI and must be started explicitly with aid dashboard start node or aid dashboard start python. The two are independent; starting the web dashboard does not affect the text status screen.

---

Subcommands

aid add

Install one or more AID tool profiles into the current project.

aid add claude-code
aid add codex,cursor            # multiple tools at once
aid add claude-code --version 1.1.0   # pin to a specific version
aid add claude-code --from-bundle aid-claude-code-v1.1.0.tar.gz  # offline

aid update

Update installed tool profiles to the latest release, or update the aid CLI itself.

aid update                       # update all installed tools
aid update claude-code           # update one tool
aid update --version 1.1.0       # update to a pinned version
aid update self                  # update the aid CLI (channel-aware)

aid update self detects the install channel and performs the upgrade automatically:

| Channel | What aid update self does | |---------|------------------------------| | curl/irm bootstrap | Re-runs the bootstrap script (install.sh / install.ps1) | | npm | Runs npm install -g aid-installer@latest (elevates with sudo if the install location is root-owned) | | PyPI/pipx | Runs pipx upgrade aid-installer |

aid remove

Remove tool profiles from the current project, or remove the aid CLI itself.

aid remove                       # remove ALL AID from this project (asks to confirm)
aid remove claude-code           # remove one tool
aid remove self                  # remove the global aid CLI (asks to confirm)

Removal is manifest-driven: only files that aid add wrote are removed. Files you edited are left in place.

aid status

Show the AID install state of the current project.

aid status

Output example:

AID 1.1.0  (project: /path/to/your/project)
Installed tools:
  claude-code   v1.1.0   root: CLAUDE.md (owned)

Exit 7 when no AID install is found in the current directory.

aid version

Print the version of the global aid CLI.

aid version

This prints the CLI version from ~/.aid/VERSION — not the version of tools installed in the current project (those are in .aid/.aid-manifest.json).

aid dashboard

Start or stop the local web dashboard. The dashboard is a read-only browser UI that shows all registered AID projects and their pipeline state. It is separate from the bare aid text status screen.

aid dashboard start node              # start using Node as the server runtime
aid dashboard start python            # start using Python (python3) as the server runtime
aid dashboard start node --port 9000  # use a custom port (default: 8787)
aid dashboard start node --remote     # also expose over your private tailnet
aid dashboard stop                    # stop the running dashboard (idempotent)

Syntax:

aid dashboard start <node|python> [--port <n>] [--remote]
aid dashboard stop

| Argument / Flag | start | stop | Description | |-----------------|:-------:|:------:|-------------| | node | python | required | — | Server runtime. Uses node or python3 from PATH. | | --port <n> | optional | — | Listen port on 127.0.0.1. Integer 1024–65535, default 8787. | | --remote | optional | — | Expose the dashboard over a private tailnet (Tailscale). Never binds publicly. |

The server always binds to 127.0.0.1 only. stop is idempotent — it is safe to call when the dashboard is already stopped. stop also tears down any active --remote tailnet exposure.

--remote requires Tailscale to be installed, running, and logged in on the host. If those conditions are not met, the command fails with an explicit error and the local server continues running. See the Dashboard guide for ACL-grant setup.

Exit codes specific to dashboard:

• 8 — dashboard is already running (run aid dashboard stop first).
• 9 — the requested runtime (node or python3) is not on PATH.
• 10 — --remote requested but the tailnet exposure mechanism is unavailable.

aid projects

Manage the set of projects this aid installation tracks. The registry stores project paths only; it does not install or remove tools.

aid projects                          # list all registered projects (same as list)
aid projects list                     # list: state, tools, tier; * marks cwd
aid projects list --verbose           # also print the registry source file for each entry
aid projects add                      # register cwd (requires .aid/ to exist)
aid projects add /path/to/project     # register a specific path
aid projects add --local              # force user tier
aid projects add --shared             # force shared tier (global install only)
aid projects remove                   # unregister cwd
aid projects remove /path/to/project  # unregister a specific path
aid projects scan                     # crawl $HOME and register every discovered .aid/ project
aid projects scan --path /path/to/dir # scan only that folder's subtree
aid projects scan --all               # scan the whole machine (Windows fixed drives; Unix from /)
aid projects scan --dry-run           # preview what scan would register; write nothing

Syntax:

aid projects [list] [--local|--shared] [--verbose]
aid projects add  [<path>] [--local|--shared]
aid projects remove [<path>]
aid projects scan [--path <folder>|--all] [--dry-run] [--depth <n>]
                  [--include-network] [--include-removable] [--local|--shared] [--verbose]

list output columns:

| Column | Values | |--------|--------| | Marker | * = current directory; blank otherwise | | Path | full absolute path (always shown) | | State | vX.Y.Z (tracked) / untracked / no-aid / missing | | Tools | comma-separated installed tool IDs | | Tier | user or shared |

With --verbose, each entry is followed by an indented registry: <file> line identifying the registry file that contains it.

Unregistered projects whose cwd has a .aid/ directory appear as a footnote in list output, with a prompt to run aid projects add.

Tier is resolved deterministically — no interactive prompt. A path under $HOME on any install type resolves to user. A path outside $HOME on a global install resolves to shared. Use --local or --shared to override.

add is idempotent. remove is idempotent and works even when the project directory no longer exists (stale entry cleanup).

aid add <tool> and aid remove automatically register and unregister the project in the registry; you only need aid projects add to manually register a project that was set up outside the normal aid add flow.

scan crawls the filesystem for folders containing a .aid/ and registers each one. It is register-only: it never installs, updates, or migrates a project, and never writes inside a discovered project’s .aid/. Each discovered project’s version is read from its manifest and reported (untracked if the .aid/ has no valid manifest). A project already registered is reported as already-registered and skipped — its existing registry record is left unchanged. A project nested inside another discovered project is not separately found: once a project is discovered, its whole subtree (including any nested .aid/) is pruned from the scan.

Directory exclusions. Before recursing into a folder, scan first checks whether it is itself a project (a valid .aid/ inside it) — that check always runs first, so a folder whose own name happens to match a pruned name (a project literally named build, bin, or .vscode, for example) is still discovered. Only after that check does scan test the folder’s basename, exact match, case-insensitively, against two built-in prune sets:

• Tier A — heavy/cache/build/IDE/AI-tool directories (node_modules, .git, dist, build, .venv, __pycache__, .cache, .vscode, .idea, .cursor, .claude, AppData, tmp, and many more). Pruned at any depth, in every scan mode — the HOME default, --path, and --all alike.
• Tier B — OS/system directories (Windows, Program Files, ProgramData, proc, sys, dev, $Recycle.Bin, System Volume Information, and similar). Pruned only under --all, and only as an immediate child of a scanned drive/filesystem root — never under the HOME default or --path, and never deeper than one level below an --all root. Tier B is fixed and not user-configurable.

scan-config.yml. Tier A’s built-in defaults can be extended with your own directory names via a user-level scan-config.yml, read once per run alongside registry.yml at the CLI state home ($AID_STATE_HOME, i.e. ~/.aid on a per-user install). The file holds a schema: 1 marker and a prune_dirs: block list:

schema: 1
prune_dirs:
  - node_modules
  - .git
  - my-local-cache

Entries are unioned with the built-in Tier-A set (case-insensitive, deduplicated) — the file can only add names, never remove or disable a built-in default, and it has no effect on Tier B. A missing, unreadable, or prune_dirs-less file is not an error: scan falls back to exactly the built-in set. On the first non---dry-run scan, if no scan-config.yml exists yet, one is seeded with the current built-in Tier-A defaults so there is something discoverable to edit; --dry-run never creates it, and an existing file is never overwritten — your edits always survive later scans.

scan flags:

| Flag | Default | Description | |------|---------|-------------| | (no scope flag) | — | Scan the user’s HOME directory ($HOME / %USERPROFILE%); no drive enumeration. | | --path <folder> | — | Scan only <folder>’s subtree instead of home. Mutually exclusive with --all. A non-directory <folder> is a usage error (exit 2). | | --all | off | Scan the whole machine — the only mode that enumerates drives: Windows local fixed drives (network/removable excluded by default); Unix from /. Mutually exclusive with --path. | | --dry-run | off | Preview what would be registered; write nothing. | | --depth <n> | built-in safety cap | Cap recursion at <n> levels below each scan root. <n> must be a non-negative integer; a non-integer or negative value is a usage error (exit 2). | | --include-network | off | Windows --all only: include network drives (excluded by default). Requires --all — a usage error (exit 2) without it. On Unix, accepted but inert (drive-type filtering is Windows-only) and emits a one-line stderr note. | | --include-removable | off | Windows --all only: include removable drives (excluded by default). Requires --all — a usage error (exit 2) without it. On Unix, accepted but inert and emits a one-line stderr note. | | --local / --shared | --local (forced) | Tier override, identical semantics to aid projects add. scan always forces the user tier unless --shared is given, so a bulk scan never elevates privileges. | | --verbose | off | Print extra per-project / per-root detail. |

---

aid chat

A channel between AI coding sessions — the same tool or different ones, on this machine or another on your LAN. A session that is idle when a message arrives is woken with the message already in hand, so the recipient acts without anybody typing.

aid chat node start                              # start this machine's hub
aid chat register --tool cursor                  # bind an identity; prints a minted <adjective>-<noun> name
aid chat hook --tool cursor --install            # install the stop hook that does the waking
aid chat roster                                  # who is available, across machines
aid chat open --channel pair                     # create and join a channel
aid chat connect --target green-giraffe          # pull a named peer into it
aid chat send --body 'ready when you are'        # say something
aid chat inbox                                   # read what arrived
aid chat ack --cursor 4                          # acknowledge up to a position

Syntax:

aid chat node start|stop|status [--port <n>]
aid chat register [--name <n>] --tool <host>     bind an identity for this directory
aid chat rename [--name <old>] --to <new>        rename mid-conversation; keeps the channel
aid chat open|join|leave [--name <n>] [--channel <c>]
aid chat list|roster [--name <n>]                channels here / who is available anywhere
aid chat connect [--name <n>] --target <peer>    pull a peer in; no accept step
aid chat send [--name <n>] --body <text> [--mention <p> | --whisper-to <p>]
aid chat inbox|ack [--name <n>] [--cursor <seq>]
aid chat heartbeat [--name <n>]                  keep this session from being reaped
aid chat hook --tool <host> [--timeout <s>] [--check | --install | --uninstall] [--yes]
aid chat peers [--add|--remove --machine <host:port> | --discover]
aid chat show|audit|evict|retention|reap ...     operator surface

--name is optional. Omitted, the node resolves the name registered for this directory and this tool. Two sessions of the same tool in one directory need --name or AID_CHAT_SESSION, and a command that cannot choose says so and lists the candidates rather than guessing.

Delivery is per-speaker FIFO. Every member sees one speaker’s messages in the order that speaker sent them; two speakers’ messages carry no promised relative order. Messages are durable while the channel is open, so a peer that restarts picks up where it left off. A channel closes when its last member leaves, and its log is discarded with it.

aid chat hook --install writes your host tool’s settings

It is the only command in AID that does. It writes user-scope settings only, merges rather than overwriting (your other settings and your own stop hooks survive), takes a backup, refuses any git-tracked settings file — which would commit one machine’s absolute paths into every checkout — and asks before writing. --uninstall removes only AID’s own entry. Both are idempotent.

The operator verbs are not in the agent’s skill

show, audit, evict and retention exist on the CLI because an operator with no way to evict a stuck session has no remedy. They are deliberately absent from the chat skill an agent reads. That is a description of what the agent is told about, not a security boundary: any session that can run shell commands can invoke the whole CLI.

---

Flags

Bash / Linux / macOS

| Flag | Applies to | Default | Description | |------|-----------|---------|-------------| | --version <v> | add, update | latest | Pin to a release version (1.0.0 or v1.0.0). Mutually exclusive with --from-bundle. | | --from-bundle <path> | add, update | — | Offline install from a tarball (single tool) or directory of tarballs. No network required. | | --force | add, update, remove | off | Overwrite differing files; skip confirmation prompts. | | --verbose | all | off | Print per-file Copied: / Up to date: / Updated: / Removed: lines. | | --target <dir> | all | . (cwd) | Project root. Must exist; missing target is a usage error (exit 2). | | --no-path | bootstrap, update self | off | Skip automatic PATH wiring during bootstrap. |

PowerShell (Windows)

PowerShell flags use the same words; the - prefix is accepted alongside --: -Force, -Verbose, -Version <v>, -FromBundle <path>, -Target <dir>, -NoPath.

| Flag | Applies to | Default | Description | |------|-----------|---------|-------------| | -Version <v> | Add, Update | latest | Pin to a release version. Mutually exclusive with -FromBundle. | | -FromBundle <path> | Add, Update | — | Offline install from tarball or directory. | | -Force | Add, Update, Remove | off | Overwrite differing files; skip prompts. | | -Verbose | all | off | Verbose per-file output. | | -TargetDirectory <dir> | all | . (cwd) | Project root. | | -NoPath | bootstrap, Update self | off | Skip PATH wiring. |

---

Exit codes

| Code | Meaning | |------|---------| | 0 | Success. “Nothing to do” is also success. | | 1 | Generic runtime failure (extract failed, write failed). | | 2 | Usage error: unknown subcommand, bad argument, ambiguous tool, missing target directory, --from-bundle + --version together. | | 3 | Network/fetch failure: download or latest-release resolution failed. | | 4 | Checksum mismatch: SHA-256 of downloaded file did not match SHA256SUMS. | | 5 | Protect-on-diff: at least one root agent file was blocked. Other files were installed. Review the .aid-new file and merge or re-run with --force. | | 6 | No manifest: remove or update found no .aid-manifest.json (nothing installed). | | 7 | aid status / bare aid: no AID install found in current directory. |

---

Environment variables

User-facing

| Variable | Equivalent flag / effect | |----------|--------------------------| | AID_TOOL | Positional tool argument for add/remove/update. Also used by bootstrap convenience-chain. | | AID_VERSION | --version | | AID_TARGET | --target | | AID_FORCE | --force — set to 1 or true. | | AID_VERBOSE | --verbose — set to 1. | | AID_NO_UPDATE_CHECK | Set to 1 to permanently disable the update-available notice. | | AID_HOME | Override the global CLI install directory (default: ~/.aid on Unix, %LOCALAPPDATA%\aid on Windows). | | AID_NO_PATH | Set to 1 to skip PATH wiring during bootstrap or update self. |

Advanced / test hooks

| Variable | Effect | |----------|--------| | AID_LIB_PATH | Absolute path to a local aid-install-core.sh — bypasses remote fetch. | | AID_LIB_BASE | Base URL for remote lib fetch. | | AID_SUMS_URL | Override URL for SHA256SUMS verification file. | | AID_INSECURE_SKIP_LIB_VERIFY | Set to 1 to bypass lib checksum verification. INSECURE — test environments only. |

---

Canonical tool IDs

| Tool ID | Installs into | Root agent file | |---------|--------------|-----------------| | claude-code | .claude/ | CLAUDE.md | | codex | .codex/ | AGENTS.md | | cursor | .cursor/ | AGENTS.md | | copilot-cli | .github/ | AGENTS.md | | antigravity | .agent/ | AGENTS.md |

Tool IDs are case-insensitive. On Windows, PascalCase aliases are also accepted: ClaudeCode, Codex, Cursor, CopilotCli, Antigravity.

---

Tool auto-detect

When aid add is run without a tool name, the CLI probes the current directory:

| Marker present | Detected tool | |----------------|---------------| | .claude/ dir | claude-code | | .codex/ dir | codex | | .cursor/ dir | cursor | | .github/ with AID-specific children | copilot-cli | | .agent/ dir | antigravity |

• Exactly one marker → that tool is used.
• Zero markers → error (exit 2): cannot auto-detect host tool; pass tool name as argument.
• More than one marker → error (exit 2): ambiguous host tool (found: X, Y).

---

Install channels

For bootstrapping the aid CLI itself (once per machine), see the Installation guide.

| Channel | Requires | |---------|----------| | curl … \| bash (Linux/macOS) | Bash | | irm … \| iex (Windows) | PowerShell 5.1+ | | npm install -g aid-installer | Node ≥18 | | pipx install aid-installer | Python ≥3.8 | | --from-bundle (offline) | Bash or PowerShell 5.1+ |