Profiles

A profile is a git repository that carries everything an agent needs — the AGENTS.md template plus RULES.md, rules/, tools/ and skills/ — versioned together. agents-cli clones it into a canonical location, pins it to a release tag, and renders a physical AGENTS.md into each project that binds to it.

New to profiles? Start with Authoring a profile to produce one from the template repository; this page describes how it behaves once registered.

Why physical files instead of a symlink

Agents (Codex, Claude Code, Gemini CLI, …) don't reliably expand variables ($HOME, {{PROFILE_HOME}}) at runtime, so a shared AGENTS.md can't carry absolute per-project paths. agents-cli solves this by rendering the profile's template into each project with the paths already resolved — no runtime expansion, and a central registry of every bound project.

There is no "active profile": each project references its profile explicitly. Re-running install --project with a different profile rebinds that project.

Where a profile lives

install --profile always clones into the canonical tree, so backups and ls ~/.config/agents-cli/profiles/ are a reliable source of truth:

~/.config/agents-cli/profiles/<name>/

($XDG_CONFIG_HOME is respected.) The profile must be complete — AGENTS.md, RULES.md, rules/, tools/, skills/ — or the install is refused with the list of missing items.

Versioning by release tags

install / update --profile operate only on vX.Y.Z release tags (SemVer):

install --profile pins the highest release tag, or the one given by --version.
update --profile shows current → target and only applies after confirmation (or --yes).
The pinned version is recorded in profiles.yaml and shown by list --profile.

A profile repository without any vX.Y.Z tag fails with a message asking you to cut a release. Legacy profiles without a recorded version fall back to the tag at HEAD.

Binding a profile to a project

cd ~/Dev/meu-projeto
agents-cli install --project beta        # render AGENTS.md from profile "beta"

agents-cli install --project experimental  # rebind: re-render from another profile

agents-cli update --project              # re-render after "update --profile" changed the template

agents-cli doctor --project              # validate every installation

agents-cli remove --project              # uninstall (removes the generated file if unchanged) + unregister

The generated AGENTS.md is a physical file (not a symlink) and is added to the project's .gitignore automatically. The target directory need not be a git repository.

Template placeholders

The profile's AGENTS.md template may use the tokens below; they are substituted literally at render time (unknown tokens are preserved intact):

Placeholder	Expands to
`{{AGENTS_PROFILE_HOME}}`	Absolute path of the installed profile (no trailing slash).
`{{AGENTS_PROFILE_NAME}}`	Name of the profile that generated the `AGENTS.md`.
`{{AGENTS_PROJECT_NAME}}`	Registry label of the project (defaults to the folder name).

Drift detection

The project registry stores a hash of the generated AGENTS.md. update, remove and doctor compare the file on disk against that hash, so hand-made edits are preserved unless you pass --force. Project status surfaces this as ok, modified, stale, missing-file, legacy-symlink, …

Files that back a profile

Path	Purpose
`~/.config/agents-cli/profiles.yaml`	YAML registry of registered profiles (XDG-aware).
`~/.config/agents-cli/profiles/<name>/`	Canonical directory for each profile (CLI-managed clone).
`~/.config/agents-cli/projects.yaml`	YAML registry of per-project installations, including the generated `AGENTS.md` hash.
`<repo>/AGENTS.md`	The physical file rendered by `install --project` (git-ignored).

Example `profiles.yaml`

version: 1
profiles:
  - name: alpha
    path: /Users/lucas/Dev/example-org/agents
    description: Profile ALPHA
    created_at: 2026-06-05T20:00:00Z
    default_branch: main
    remote: git@bitbucket.org:example-org/agents.git
    version: v1.2.0
  - name: beta
    path: /Users/lucas/.agents-beta
    description: Profile BETA
    created_at: 2026-06-05T20:30:00Z
    default_branch: main
    remote: git@example.com:workspace/agents.git
    version: v0.3.1

Guarantees

Atomic writes — the rendered AGENTS.md is written via a temp file + os.Rename, so readers never see a partial file.
Idempotence — re-running install --project with the file intact re-renders in place, with no prompt or backup.
No clobbering — an AGENTS.md the CLI didn't generate is only overwritten with confirmation / --force, and after a timestamped backup.
Safe permissions — config and log files are created 0600, directories 0700, the generated AGENTS.md 0644.

Every mutating operation is also recorded in the audit log.