Usage

This page documents each agents-cli subcommand. For the mechanical flag list rendered live from the generated docs, see the Commands & flags reference.

agents-cli and acli are interchangeable; examples below use whichever is shorter.

The `--profile` / `--project` model

Every verb operates on exactly one target, selected by a mode flag:

--profile — a registered profile: a git repository carrying the AGENTS.md template (plus RULES.md, rules/, tools/, skills/), cloned into ~/.config/agents-cli/profiles/<name>/ and pinned to a release tag.
--project — a project's rendered AGENTS.md: the physical file install --project writes into a repo and tracks in the registry.

The two modes are mutually exclusive and at least one is required. There is no "active profile": each project references its profile explicitly.

Installation

The recommended installer downloads the latest release, verifies its SHA-256, and installs into /usr/local/bin (or ~/.local/bin if the former isn't writable):

curl -fsSL https://acli.chagbrasil.com/install/install.sh | sh

Pin a version, or force the install directory:

curl -fsSL https://acli.chagbrasil.com/install/install.sh | sh -s -- --version v1.2.3
curl -fsSL https://acli.chagbrasil.com/install/install.sh | sh -s -- --dir ~/.local/bin

The installer is idempotent (re-running upgrades in place) and also creates an acli symlink alongside the binary. From source (requires Go 1.26+):

go install gitlab.com/chagbrasil/agents-cli/cmd/agents-cli@latest

Check what you have:

agents-cli version

`install`

install has two modes.

`install --profile`: clone a profile repo and register it

Clones a Git URL over SSH into ~/.config/agents-cli/profiles/<name>/, pins it to the highest vX.Y.Z release tag, and records the version.

# <name> defaults to the URL's last path segment
agents-cli install --profile git@example.com:workspace/agents.git --name beta

# pin a specific release tag at install time
agents-cli install --profile git@example.com:workspace/agents.git --name beta --version v1.2.0

Authentication is delegated to your SSH agent and ~/.ssh/config; agents-cli never touches credentials. Installing over an existing profile name is refused — remove it first with remove --profile <name>.

`install --project`: render AGENTS.md into a project

Renders a physical AGENTS.md into [path] (default: current directory) from the profile's template, expanding the placeholders, adds the file to .gitignore, and registers the binding.

cd ~/Dev/meu-projeto
agents-cli install --project beta

# or from outside the repo, passing the path
agents-cli install --project beta ~/Dev/outro-projeto

Re-running with a different profile rebinds the project (re-renders AGENTS.md). The target need not be a git repo; when it is (with an origin), the remote URL is captured best-effort. An AGENTS.md the CLI did not generate is backed up to AGENTS.md.bak-<timestamp> and only overwritten with confirmation or --force. See Profiles for the placeholder table.

`list`

agents-cli list --profile   # registered profiles, including the pinned VERSION
agents-cli list --project   # installations: NAME, profile, VERSION and status

Project status is one of ok, missing-file, modified, stale, legacy-symlink, …. In a terminal, tables are highlighted and status is colour-coded by severity.

`show`

Details one entry. Omit the identifier to pick from the registered entries by name (a numbered menu in a TTY; a list + non-zero exit in CI).

agents-cli show --profile beta    # path, description, branch, HEAD, remote, status
agents-cli show --project         # the current registered project, or a menu

For scripts, --json emits a single JSON object (or a JSON array of every entry when the identifier is omitted) and never prompts. Keys are stable snake_case; timestamps are RFC 3339.

agents-cli show --profile beta --json
agents-cli show --project --json    # array of all projects

Project verbs accept either the name or the path: show --project playbooks resolves the registered project from any directory.

`update`

`update --profile`: move to the newest release tag

Moves a profile to the highest vX.Y.Z release tag of its repository (refuses a dirty tree, assumes the origin remote). It shows current → target and asks before applying; --yes confirms without a prompt (required to apply non-interactively).

agents-cli update --profile beta          # by name (prompts in a terminal)
agents-cli update --profile beta --yes    # scripts / CI
agents-cli update --profile --all --yes   # every registered profile

`update --project`: re-render after a profile change

Re-renders a project's AGENTS.md from its bound profile — useful right after update --profile changed the template.

agents-cli update --project           # re-render the current project
agents-cli update --project --all      # re-render every project that needs it (status "stale")

--all skips projects already in sync; --force also covers modified / legacy-symlink installs (backing up first).

`remove`

# profile: drops the registry entry AND the canonical directory
agents-cli remove --profile alpha

# keep the directory on disk, drop only the registry entry
agents-cli remove --profile alpha --keep-files

# project: uninstall (removes the generated AGENTS.md if unchanged) + unregister
agents-cli remove --project

When a profile is bound to projects, a terminal prompts whether to unbind them; in CI you must choose explicitly:

agents-cli remove --profile alpha --remove-installations   # unbind every project first
agents-cli remove --profile alpha --keep-installations     # leave the (now stale) AGENTS.md files

`doctor`

agents-cli doctor --profile   # validate every registered profile (path, git repo)
agents-cli doctor --project   # validate every installed project

`version`

agents-cli version   # version, commit, build date and platform

Interactive output, colours and `--no-color`

In an interactive terminal the CLI uses the Charm toolkit for highlighted tables, colour-coded status, spinners (during git clone), a batch progress bar (update --project --all), arrow menus (show, remove) and confirmation prompts (update --profile). It degrades gracefully: when output/input isn't a terminal — or in CI, or with --json — it falls back to plain text and numbered prompts, byte-for-byte identical to the non-styled output.

Disable styling with the global --no-color flag or the NO_COLOR environment variable (TERM=dumb also disables it):

agents-cli list --profile --no-color
NO_COLOR=1 agents-cli doctor --project

Common workflows

Set up a profile and bind a project

curl -fsSL https://acli.chagbrasil.com/install/install.sh | sh
agents-cli install --profile git@example.com:workspace/agents.git --name beta
cd ~/Dev/meu-projeto && agents-cli install --project beta
agents-cli doctor --project

Update a profile and refresh every project

agents-cli update --profile beta --yes
agents-cli update --project --all