First run

From a fresh install to a running agent in four commands, then where agents-cli keeps everything.

1. Set up

agents setup is the first-time bootstrap. It clones the system config repo into ~/.agents/.system/ and imports any agent CLIs already installed on the machine.

agents setup

# then install the CLIs from agents.yaml and sync resources into each version home
agents repo refresh -y

Re-run agents setup --force to repair a corrupted ~/.agents/.system/. Pass --no-system-repo to skip the clone and populate ~/.agents/.system/ yourself.

2. See what is installed

agents view lists every agent CLI it found, which versions are present, and which account each is signed into. Pass an agent@version to inspect that version's resources.

agents view                 # every installed CLI + version + signed-in status
agents view claude@default  # resources for the active Claude version

3. Run your first agent

Drive a signed-in profile. A prompt runs headless; omit the prompt to drop into an interactive session under the resolved version.

agents run claude "summarize the last 10 commits" --mode plan
agents run claude                                   # interactive TUI

--mode plan keeps the first run read-only — no writes, no shell side-effects — so you can watch the agent work without risk.

Where things live

Everything agents-cli manages sits under ~/.agents/. The config layers are designed to be safely version-controlled — no raw credentials touch disk.

~/.agents/ — your config: skills, commands, hooks, rules, MCP servers, and agents.yaml. Push it to a git host with agents repo push and pull it on every machine.
~/.agents/.system/ — the system layer, cloned by agents setup. Shared defaults you inherit but rarely edit.
~/.agents/versions/<agent>/<version>/home/ — each installed CLI's home. ~/.claude/, ~/.codex/, and the rest are symlinks into here.
./.agents/ — the project layer at a repo root. Per-project rules merged in at spawn time.

See config layers for how system, you, and project combine at resolution time.

When something looks off

agents doctor diagnoses CLI availability, sync status, and resource divergence. Run it first whenever a command behaves unexpectedly.

agents doctor              # availability + sync status + orphans across defaults
agents doctor claude       # one agent, all its installed versions
agents doctor --fix        # heal every gap it finds

Run — the full flag reference for driving any CLI.
Pin versions — lock each CLI per project.
Secrets — Keychain bundles, scoped per process.