CLI Reference — Overview

The aasm binary (crate aa-cli) is the operator front-end for Agent Assembly. It talks to a running aa-gateway over its HTTP / OpenAPI surface (default http://localhost:8080) for registry, policy, audit, approval, cost, and topology operations, and manages local daemon processes (gateway, proxy, dashboard) directly.

Invocation

aasm [OPTIONS] <COMMAND> [SUBCOMMAND] [ARGS]

Every command supports --help (-h for a one-line summary) at each layer:

aasm --help               # list all top-level commands
aasm policy --help        # list policy subcommands
aasm policy apply --help  # flags + arguments for one subcommand

Global options

These flags are defined on the root parser (aa-cli/src/lib.rs) and are global — they may be passed before the command or on any subcommand.

Flag	Type	Default	Description
`--context <CONTEXT>`	string	(default context, if any)	Named context from `~/.aa/config.yaml` to use for the API URL and key.
`--output <OUTPUT>`	`table` \| `json` \| `yaml`	`table`	Output format for list/get commands.
`--api-url <API_URL>`	string	`http://localhost:8080`	Override the gateway API base URL. Takes precedence over the resolved context.
`--api-key <API_KEY>`	string	(none)	Override the API key. Takes precedence over the context’s stored key. For interactive use prefer `aasm login` over putting the key on argv/env (see the note below).
`-h, --help`	flag	—	Print help.
`-V, --version`	flag	—	Print the `aasm` version.

Authenticating. --api-key / AASM_API_KEY still work and are the right choice for CI and other non-interactive environments. For interactive use, prefer aasm login: it exchanges the key once for a short-lived scoped session (stored per context) so the raw key never sits on argv, in your shell history, or in the environment. See Authentication for the session model, expiry/auto-refresh, and the login / logout / whoami commands.

Several commands also expose a local --output or --json flag that overrides the global --output for that command only (e.g. aasm logs --output json, aasm status --json, aasm gateway status --json). These are called out on the relevant command pages.

Output formats

--output (source: aa-cli/src/output.rs) selects how list/get commands render:

table (default) — human-readable, colorized tables via comfy-table.
json — machine-readable pretty JSON.
yaml — machine-readable YAML.

Commands that stream (aasm logs --follow, aasm approvals watch), visualize (aasm trace, aasm topology tree), or open a TUI (aasm dashboard) ignore --output where it does not apply.

Config and context resolution

CLI configuration lives at ~/.aa/config.yaml (source: aa-cli/src/config.rs). It holds named contexts (connection profiles), an optional default context, and dashboard settings:

default_context: production
contexts:
  production:
    api_url: https://api.example.com
    api_key: prod-key
  staging:
    api_url: https://staging.example.com
dashboard:
  port: 3000
  auto_open: false

The active API URL and key are resolved with this precedence (highest first):

Explicit --api-url / --api-key flags.
The named context — --context <name>, otherwise default_context.
Built-in default URL http://localhost:8080 (no key).

Manage contexts with the aasm context command group.

Sessions live separately from config. When you aasm login, the resulting scoped session is stored in ~/.aa/credentials.yaml (locked 0600), kept distinct from ~/.aa/config.yaml so that clearing a session (aasm logout) never rewrites your context definitions. See Authentication.

Note on paths. The CLI config file is ~/.aa/config.yaml. Separately, the locally-managed gateway uses ~/.aasm/ for its runtime artifacts — ~/.aasm/config.yaml (gateway config, see aasm start), ~/.aasm/policy.yaml, ~/.aasm/logs/gateway.log, and ~/.aasm/gateway.pid. These are distinct files.

Exit codes

aasm follows the standard convention:

0 — success.
non-zero — failure. Common causes: the gateway is unreachable, the API returned a non-2xx status, a named context was not found, a file failed to parse, or a validation/simulation step found problems.

Some commands give the exit code a documented meaning so it can gate CI:

Command	Non-zero exit means
`aasm status`	Gateway unreachable, any agent has violations, or storage health probe reports `unavailable`.
`aasm policy simulate`	The simulation detected policy violations.
`aasm policy validate`, `aasm config validate`	The file is invalid (error printed to stderr).
`aasm audit verify-chain`	The audit hash chain failed verification.
`aasm integrations`	One of eight distinct failure outcomes — `1` and `3`–`9` each name a different next action (`2` is left to `clap`). They are the non-zero half of the nine-value `Outcome` vocabulary. See its exit-code table.

Command groups

Command	Talks to	Purpose
`aasm login` / `logout` / `whoami`	Gateway HTTP + local	Exchange an API key for a scoped session, clear it, or inspect it.
`aasm status`	Gateway HTTP	Fleet health, agents, approvals, budget at a glance.
`aasm agent`	Gateway HTTP	List, inspect, suspend, resume, kill registered agents.
`aasm policy`	Gateway HTTP + local	Apply, version, diff, simulate, validate, show policies.
`aasm topology`	Gateway HTTP	Visualize agent trees, teams, lineage, stats.
`aasm alerts`	Gateway HTTP	List, inspect, resolve governance alerts.
`aasm approvals`	Gateway HTTP + WS	Human-in-the-loop approval queue.
`aasm audit`	Gateway HTTP + local	Query, export, verify, and compliance-export audit data.
`aasm logs`	Gateway HTTP + WS	Query and stream audit-log events.
`aasm trace`	Gateway HTTP	Visualize a single session trace.
`aasm cost`	Gateway HTTP	Cost summary and monthly forecast.
`aasm dashboard`	Gateway HTTP/WS + local	TUI dashboard and embedded SPA server.
`aasm gateway`	Local process	Manage the `aa-gateway` daemon.
`aasm proxy`	Local process	Manage the `aa-proxy` sidecar and its CA.
`aasm integrations`	`aa-runtime` DI-API (UDS)	Install, verify, repair, remove Developer Integrations for AI dev tools. Not in `cargo install aasm` — see below.
`aasm start` / `aasm stop`	Local process	Start/stop the locally-managed gateway.
`aasm sandbox`	Local	Run a WASM tool under the sandbox.
`aasm config`	Local	Validate / boot an `agent-assembly.toml`.
`aasm context`	Local	Manage `~/.aa/config.yaml` contexts.
`aasm admin`	Gateway HTTP	Administrative operations (retention).
`aasm uninstall`	Local	Remove Agent Assembly tools installed via the curl installer (`--purge` also removes local data; Homebrew installs are redirected to `brew uninstall`).
`aasm version`	Gateway HTTP	CLI + gateway/api versions.
`aasm completion`	Local	Generate shell completion scripts.

Developer-only commands. Three command groups — aasm run (launch a governed AI dev tool), aasm tools (discover installed AI dev tools), and aasm integrations (the Developer Integration lifecycle — added to this set by AAASM-5309) — are gated behind the devtool region in aa-cli/src/commands/mod.rs and aa-cli/Cargo.toml.

Which channel you installed from decides whether you have them. .ci/strip-for-publish.sh removes that region in the publish-crates job of release.yml, so the strip applies to the crates.io publish and nothing else. cargo install aasm does not have the three commands. A source build (cargo build -p aa-cli), the GitHub Release tarballs, the curl installer and the Homebrew formula are all built from the unstripped tree in the build job, so those aasm binaries do have them — and their aa-runtime still carries the Developer Integration API bring-up.

aasm integrations is documented here because it is a shipped, user-facing surface on every channel except crates.io, and the omission was itself a documentation gap. aasm run and aasm tools remain undocumented in this reference. Where the strip does apply it is not cosmetic in the integrations case: a crates.io aa-runtime never binds the Developer Integration API socket, so the command would have nothing to connect to.

Last updated: 2026-08-04 by Chisanan232

Keyboard shortcuts