Profiles

A profile is, at the disk level, a directory containing whatever your agents repository expects (AGENTS.md, RULES.md, skills, tools, templates, …). agents-cli keeps a registry of these directories and exposes them under a single, stable name.

Where things live

Path	Contents
`~/.config/agents-cli/profiles.yaml`	The registry. One entry per profile (name, path, description).
`~/.config/agents-cli/profiles/<name>/`	The canonical profile directory (a copy of whatever was registered).
`~/.agents`	A symlink pointing at one of the profile directories. The "active" profile.
`~/.local/state/agents-cli/audit.log`	Append-only JSONL log of every transition.

All four paths follow XDG conventions. They can be overridden with the environment variables in the reference.

`profiles.yaml`

The registry is human-readable on purpose — you can inspect it, version it (carefully — see below), and edit it by hand in emergencies. Schema:

profiles:
  - name: alpha
    path: /Users/you/.config/agents-cli/profiles/alpha
    description: "Alpha tenant"
  - name: beta
    path: /Users/you/.config/agents-cli/profiles/beta
    description: ""

Rules enforced by the CLI:

name must match [a-z0-9][a-z0-9-]* (lowercase alphanumerics + dashes, must start with alphanumeric).
path must be an absolute path.
name must be unique across the file.

add and install validate the entry before writing the file; if any field is invalid the registry is left untouched.

Don't commit profiles.yaml to a shared repo. Paths are per-machine. Sharing profiles.yaml across machines is almost always wrong. If you want shared agent content, share the profile directory as a Git repo and use install on each machine.

The canonical profile directory

When you add or install a profile, the actual files are placed under ~/.config/agents-cli/profiles/<name>/. The original directory passed to add is copied (including .git), so the source can be safely removed afterwards.

Why a canonical location:

One predictable place to look. No more "where did I put .agents-beta again?"
update profile knows where each profile lives without re-asking.
Backup scripts and config sync tools can target a single directory.

Atomic swap

use performs the swap with rename(2) semantics:

Resolve the target profile's absolute path.
Create a temporary symlink (~/.agents.acli-tmp-XXXXXX) pointing at the target.
rename(~/.agents.acli-tmp-XXXXXX, ~/.agents) — atomic on POSIX filesystems.

If step 3 fails, the temporary symlink is cleaned up and ~/.agents is left at its previous value. There is no window in which the symlink is missing, half-written, or pointing at a partially copied directory.

This matters in practice when an agent process is reading ~/.agents/AGENTS.md in a tight loop while a use runs — it will see either the old profile or the new profile, never a broken symlink.

Editing the registry by hand

If something goes wrong (e.g. you registered a path with a typo), the recovery path is:

Stop any running agent.
Edit profiles.yaml directly.
Run acli doctor — it will refuse the file if the schema is invalid, telling you exactly which entry is the problem.
Fix and re-run doctor until it's all OK.

This is intentional. The CLI does not provide an edit subcommand — manual edits should be rare, and the existing surface (add, remove) covers the common cases.