agents-cli
GitLab

Quickstart

This page walks you from zero to a working agents-cli installation with a registered profile and an atomic swap. Total time: about two minutes.

1. Install

The one-line installer downloads the latest signed release, verifies the SHA-256 checksum, and drops the binary into /usr/local/bin (falling back to ~/.local/bin if the former isn't writable).

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

Verify it landed:

agents-cli --version

You should see something like:

agents-cli version 3.2.0

The installer also creates an acli symlink as a shorter alias — acli current is equivalent to agents-cli current.

If you prefer to build from source, use go install gitlab.com/chagbrasil/agents-cli/cmd/agents-cli@latest (requires Go 1.26+). See the Usage guide for advanced install options.

2. Register a profile

You can either add an existing directory or install a new one from a Git URL.

Option A — add an existing directory

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

Under the hood, this copies ~/.agents-alpha (including .git) into the canonical profile directory ~/.config/agents-cli/profiles/alpha/ and records it in the registry.

Option B — clone from a Git URL

agents-cli install git@example.com:workspace/agents.git --name beta --use

install uses your SSH agent and ~/.ssh/config — there's no extra credential setup. The --use flag makes the new profile active immediately after the clone.

3. List what you have

agents-cli list

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

The * marks the currently active profile.

4. Swap atomically

agents-cli use alpha

use performs an atomic rename of ~/.agents — there's no window where the symlink is missing or pointing somewhere half-broken. Every swap appends a line to the audit log:

{"ts":"2026-06-09T10:21:33Z","event":"use","from":"beta","to":"alpha","actor":"you","cwd":"/Users/you/work","exit":0}

5. Validate

When in doubt, run:

agents-cli doctor

doctor checks the symlink, the registry, and the repository state of each profile, and prints a one-line verdict per check.

Next steps

  • Read the Usage guide for every subcommand and flag.
  • Learn the Profiles model — where files live, how swaps stay atomic.
  • Skim the Audit log schema if you want to ship it to a log aggregator.