Install

Install once, point the CLI at the agents you already pay for, and run anything from one prompt.

1. Install

curl -fsSL agents-cli.sh | sh

# or, if you prefer a package manager
bun install -g @phnx-labs/agents-cli
npm install -g @phnx-labs/agents-cli

The installer drops a single binary at ~/.agents/bin/agents and symlinks ag alongside it. Both work everywhere.

2. Add a model profile

A profile is a saved (provider, model, key) triple. Add one for each combination you want to invoke. The key lives in macOS Keychain — never on disk.

agents profiles add claude
agents profiles add kimi      --provider openrouter --model moonshotai/kimi-k2.5
agents profiles add deepseek  --provider openrouter --model deepseek/deepseek-coder
agents profiles list

3. Run an agent

agents run claude "refactor the queue worker"
agents run kimi   "draft a release note for v1.20"
agents run codex  "fix the failing test in src/payments/"

Same flags work everywhere. --rotate picks the least-used account, --quiet suppresses the preamble, --stream emits stream-json for piping.

4. Pin per project

Drop an agents.yaml at the repo root. Every agents call inside the tree honors it — like .nvmrc, but for AI.

# agents.yaml
agents:
  claude: "2.1.113"
  codex:  "0.116.0"

5. Make the config travel

Your skills, commands, hooks, rules, and MCP servers live in ~/.agents/. Push it to a git host once and pull on every machine.

agents repo init
agents repo push                # mirrors ~/.agents to your remote
agents repo pull                # on the next machine

Per-project rules go in ./.agents/ and get merged in at spawn time. See config layers for how the four levels — system, you, team, project — combine.

To reach those other machines directly — run agents on them, sync sessions, push secrets — register your fleet and target any of it with one flag. agents devices sync ingests your tailnet; agents secrets push carries credential bundles across. Go multi-machine →

Uninstall

Trying agents-cli costs you nothing to undo. agents uninstall is the exact reverse of setup: it restores every config directory the CLI adopted, releases the launchers it took over on PATH, and strips the shim directory from your shell — leaving the machine as it was before you installed.

agents uninstall --dry-run   # print exactly what would change, touch nothing
agents uninstall             # restore configs, move ~/.agents aside (recoverable)
agents uninstall --purge     # same, but hard-delete ~/.agents

npm uninstall -g @phnx-labs/agents-cli   # finally, remove the package

What it guarantees:

A config agents-cli never adopted is never touched — ownership is decided structurally, not guessed.
Recoverable by default: ~/.agents (versions, sessions, secrets metadata) moves to ~/.agents.removed-<timestamp>, not deleted. --purge hard-deletes instead.
If any restore step errors, --purge self-downgrades to the recoverable move-aside — a failure can never take your only copy of a config with it.
Works on macOS, Linux, and Windows — junctions and a cross-volume ~/.agents are handled.

Config layers — system, you, team, project.
Secrets — Keychain bundles, scoped per process.
Browser profiles — let agents drive a real browser.
Changelog — what shipped recently.