agents-cli documentation

agents-cli registers, inspects, and switches between agent profiles — directories on disk (typically clones of an agents repository) — by repointing the ~/.agents symlink.

It exists because the obvious manual approach —

ln -sfn ~/.agents-beta ~/.agents

— is silent, unaudited, and easy to mistype mid-task. agents-cli replaces it with a small set of explicit commands, an atomic symlink swap, and a JSONL audit log.

Start here

• Quickstart — install, register a profile, switch.
• Usage — every subcommand with examples.
• Profiles — profiles.yaml, the canonical profile directory, atomic swap semantics.
• Audit log — JSONL schema and location.
• Releases — SemVer policy, Conventional Commits, release process.

Reference

• Commands & flags — full reference of subcommands, flags, and environment variables.

Tags

• acli is an alias symlink installed alongside agents-cli. The two binaries are interchangeable.
• Linux and macOS, amd64 and arm64. Windows is out of scope (different symlink semantics).
• No Go or Git required to install — the installer downloads a static binary.