Commands & flags

This page is the canonical, mechanical reference. Prose explanations live in Usage and Profiles.

Synopsis

agents-cli [global flags] <command> [command flags] [arguments]
acli       [global flags] <command> [command flags] [arguments]

acli is a symlink to agents-cli installed alongside it. The two are interchangeable.

Global flags

Flag	Purpose
`-h`, `--help`	Show help for the command and exit.
`-v`, `--version`	Print version, commit and build date and exit.

Subcommands

`install <git-url>`

Clone a profile repo over SSH and register it.

Flag	Default	Purpose
`-n, --name <name>`	derived from URL	Profile name to register.
`-t, --target <path>`	`~/.config/agents-cli/profiles/<name>/`	Clone destination.
`--use`	false	Activate the new profile after install.

`add <name> <path>`

Flag	Default	Purpose
`-d, --description <text>`	empty	Human description shown by `list` / `show`.

`list`

List registered profiles. The active profile is marked with *.

No flags.

`current`

Print the active profile’s name, path, branch and clean/dirty state.

No flags. Exits non-zero if ~/.agents is unset, broken, or points outside the registry.

`use <name>`

Atomically repoint ~/.agents at the named profile.

No flags. Exits non-zero if the profile is unregistered or the target directory is missing.

`show <name>`

Print full details of one profile, including description and registry metadata.

No flags.

`remove <name>`

Unregister a profile. Aliases: rm.

Flag	Default	Purpose
`--force`	false	Allow removing the active profile.

The profile directory on disk is not deleted.

`doctor`

Run the full diagnostics chain: symlink, registry consistency, per-profile git state, audit-log writability.

No flags. Exits non-zero on any FAIL.

`update profile [name]`

Fast-forward a profile’s git working tree.

Argument / flag	Default	Purpose
`[name]`	active profile	Profile to update.
`--all`	false	Update every registered profile. Exit code reflects whether any failed.

update profile refuses dirty working trees, refuses branch switches, refuses non-fast-forward pulls, and never runs reset, checkout, merge, rebase, stash or clean.

Environment variables

Variable	Default	Effect
`AGENTS_CLI_DIR`	`~/.config/agents-cli`	Root of the registry and canonical profile directory. Override to keep multiple isolated `agents-cli` setups on one machine.
`AGENTS_CLI_BASE_URL`	`https://acli.chagbrasil.com/install`	Base URL the installer uses to fetch artefacts. Used for tests and air-gapped mirrors.
`AGENTS_CLI_VERSION`	latest	Pin a version when running the installer (`sh -s -- --version vX.Y.Z` is the flag equivalent).
`XDG_CONFIG_HOME`	`~/.config`	Standard XDG override; affects `AGENTS_CLI_DIR` when the latter is unset.
`XDG_STATE_HOME`	`~/.local/state`	Standard XDG override; affects the audit-log location.
`HOME`	—	Used to expand `~` in paths. Must be set.
`USER`	—	Recorded as `actor` in the audit log. Falls back to `os/user.Current()` if unset.

Files

Path	Created by	Contents
`~/.config/agents-cli/profiles.yaml`	`add` / `install` / `remove`	Registry (YAML).
`~/.config/agents-cli/profiles/<name>/`	`add` / `install`	Canonical profile directory.
`~/.agents`	`use` (and the user, originally)	Symlink to the active profile directory.
`~/.local/state/agents-cli/audit.log`	First mutating command	JSONL audit log. See Audit log.

Exit codes

Code	Meaning
`0`	Success.
`1`	Generic failure (invalid arguments, unregistered profile, missing path, etc.). The error message on stderr explains.
`2`	Diagnostic failure — `doctor` returns this when at least one check is `FAIL`.
`3`	I/O failure — registry could not be read or written, or audit log could not be appended.
`4`	Git failure — `update profile` reports this when git refused (dirty tree, non-FF pull, etc.).

Exit codes are stable across minor versions. Any change to this table is a MAJOR bump.

Compatibility matrix

Platform	`amd64`	`arm64`
Linux	✅	✅
macOS	✅	✅
Windows	—	—

Windows is out of scope: ~/.agents symlink semantics differ enough to make a single binary uncomfortable. Use WSL.