Switch agent profiles
without breaking your flow.

Install in one line

The installer downloads the latest signed release from install.chagbrasil.com (Cloudflare R2 + Worker), verifies a SHA-256 checksum, and drops the binary into /usr/local/bin or ~/.local/bin.

$ curl -fsSL https://install.chagbrasil.com/agents-cli/install.sh | sh

Already installed? Re-run the same line — the script is idempotent and upgrades in place. Pin a version with --version vX.Y.Z.

Why agents-cli?

Multiple agent profiles in your home directory — one per client, one per project, one for experiments — usually share a single active slot at ~/.agents. Swapping between them with a raw ln -sfn works, but:

• No record of what changed

  Manual symlink swaps leave no trail. Which profile was active yesterday? Last week? You don't know.

• No safety net

  A typo silently points ~/.agents at the wrong place. The shell happily returns 0 and you only notice mid-task.

• No discovery

  There is no canonical list of registered profiles. New machines and new teammates have nothing to start from.

agents-cli adds an explicit registry (~/.config/agents-cli/profiles.yaml), an atomic use <name> swap, and a JSONL audit log at ~/.local/state/agents-cli/audit.log. Every transition is recoverable, inspectable, and scriptable.

Nine commands. That's the surface area.

Each subcommand has a single, narrow purpose. Run with --help for the full flag list — or read the Usage guide.

• install <url> Clone a profile repo over SSH and register it.
• add <name> <path> Register an existing directory as a profile.
• list List registered profiles; the active one is marked.
• current Show the active profile name, path and git state.
• use <name> Atomically repoint ~/.agents at a profile.
• show <name> Inspect one profile in detail.
• remove <name> Unregister a profile (the directory stays).
• doctor Validate symlink, registry, and repo state.
• update profile [name] Fast-forward a profile via git pull — never resets, merges, or rebases.

Every swap is logged. As JSONL.

Each use, install, add, and update appends a line to ~/.local/state/agents-cli/audit.log:

{"ts":"2026-06-09T10:21:33Z","event":"use","from":"alpha","to":"beta","actor":"lucas","cwd":"/Users/lucas/work","exit":0}
{"ts":"2026-06-09T10:21:38Z","event":"update_profile","profile":"beta","from":"7f3a8c1","to":"9e2b441","ff":true,"exit":0}

Grep, pipe into jq, ship to your log aggregator, or just read it. Nothing fancy — newline-delimited JSON in a stable schema.

Open source. Tagged releases. Signed artefacts.

• SemVer + Conventional Commits

  Every release is a SemVer tag with a Keep-a-Changelog entry and SHA-256 checksums. See the release process.

• Built in CI

  GoReleaser builds for linux/amd64, linux/arm64, darwin/amd64 and darwin/arm64. The GitLab pipeline publishes to GitLab Releases and mirrors to R2.

• Documented

  Six ADRs (architecture) and a complete reference of every flag and environment variable.