Skip to content
Casulo AI Labs AID AI Integrated Development
AID v2.3.0 is out.See what's new →
Reference

CLI & Subcommands

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

Command surface

Section titled “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 <command> -h | --help        Per-command help

Subcommands

Section titled “Subcommands”

aid add

Section titled “aid add”

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

Terminal window
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

Section titled “aid update”

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

Terminal window
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

Section titled “aid remove”

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

Terminal window
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

Section titled “aid status”

Show the AID install state of the current project.

Terminal window
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

Section titled “aid version”

Print the version of the global aid CLI.

Terminal window
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

Section titled “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.

Terminal window
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

Section titled “aid projects”

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

Terminal window
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. |

Flags

Section titled “Flags”

| 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. |

Exit codes

Section titled “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

Section titled “Environment variables”

User-facing

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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+ |

Report an issue with this page →