Usage

This page documents each agents-cli subcommand. For the full flag reference (including environment variables and exit codes), see the reference.

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

Installation

The recommended installer:

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

Pin a version:

curl -fsSL https://acli.chagbrasil.com/install/install.sh | sh -s -- --version v3.0.0

Force the install directory:

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

The installer is idempotent — re-running it upgrades in place.

From source (requires Go 1.26+):

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

install — clone a profile repo and register it

Clones a Git URL over SSH and registers the result as a profile. By default the clone lands in ~/.config/agents-cli/profiles/<name>/, where <name> is derived from the last segment of the URL.

acli install git@example.com:workspace/agents.git

Flags:

Flag	Purpose
--name <name>	Override the auto-derived profile name.
--target <path>	Use a different clone destination (then registered with that path).
--use	Activate the new profile immediately after install.

Authentication is delegated to your SSH agent and ~/.ssh/config — agents-cli never touches credentials.

add — register an existing directory

Registers a directory that already exists on disk as a profile. The directory is copied into ~/.config/agents-cli/profiles/<name>/ so every registered profile lives in the canonical location.

acli add alpha ~/.agents-alpha --description "Alpha tenant"

Flag	Purpose
--description <text>	Human description shown by list and show.

list — list registered profiles

acli list

* beta    /Users/you/.config/agents-cli/profiles/beta     main         (clean)
  alpha   /Users/you/.config/agents-cli/profiles/alpha    main         (clean)
  gamma   /Users/you/.config/agents-cli/profiles/gamma    main         (dirty)

* marks the active profile. The branch and clean/dirty state come from running git against the profile directory.

current — show the active profile

acli current

Prints the name, path, current branch, and a one-line git status of whichever profile ~/.agents points at. Exits non-zero if ~/.agents is broken or unregistered.

use — atomically swap the active profile

acli use alpha

Performs an atomic rename(2) of ~/.agents — there is no instant where the symlink is missing or partially updated. Every successful swap appends an entry to the audit log.

use refuses to swap to a profile that doesn’t exist or whose target directory is missing. It does not validate the contents of the profile beyond that — use doctor for deeper checks.

show — inspect one profile

acli show beta

Prints everything list shows for that profile, plus the description, remote URL, last commit, and any extra metadata stored in profiles.yaml.

remove — unregister a profile

acli remove beta

Flag	Purpose
--force	Allow removing the currently active profile (~/.agents then needs to be repointed manually).

remove only deletes the entry from profiles.yaml — the profile directory on disk is left alone, so accidental removals are recoverable with add.

doctor — validate the setup

acli doctor

Runs a chain of checks:

• Does ~/.agents exist and point at a registered profile?
• Does each registered path still exist on disk?
• Is each profile’s working tree clean? On a branch? Tracking a remote?
• Is the audit-log file writable?

Each check prints OK / WARN / FAIL. Exit code is non-zero if any check fails.

update profile — fast-forward a profile via git

acli update profile beta        # by name
acli update profile             # the currently active one
acli update profile --all       # every registered profile

update profile is intentionally conservative:

• Refuses dirty working trees.
• Refuses to switch branches.
• Refuses non-fast-forward pulls.
• Never runs reset, checkout, merge, rebase, stash, or clean.
• If HEAD already matches the remote, nothing is mutated.

This makes it safe to run inside an agent loop or a cron job without worrying about local changes being lost.

Common workflows

One-time setup on a new machine

curl -fsSL https://acli.chagbrasil.com/install/install.sh | sh
acli install git@example.com:workspace/agents.git --name beta --use
acli doctor

Switch profile before starting a task

acli use alpha
acli current   # sanity check

Keep all profiles up to date in CI / cron

acli update profile --all

Exit code is non-zero if any profile failed to update, but the command attempts every profile (best-effort).