Audit log

agents-cli appends one JSON line to an audit log for every mutating operation, so you always have a recoverable, inspectable, scriptable record of what changed.

Location

~/.local/state/agents-cli/audit.log

$XDG_STATE_HOME is respected, and AGENTS_CLI_HISTORY overrides the path outright (handy for tests and sandboxing). The file is created 0600 inside a 0700 directory.

Versions before the history.log → audit.log rename wrote to history.log in the same directory. An old file, if present, is preserved but no longer used — move or ignore it.

Format

The log is JSONL: one JSON object per line, appended in order. Each entry records the intent, the outcome, the profile involved and the paths touched, keyed by a trace_id.

{"trace_id":"a1b2c3d4...","ts":"2026-06-05T20:10:00Z","intent":"install","outcome":"ok","profile":"beta","to":"/Users/lucas/.config/agents-cli/profiles/beta","extra":{"url":"git@example.com:workspace/agents.git"}}
{"trace_id":"e5f6...","ts":"2026-06-05T20:12:30Z","intent":"project-install","outcome":"ok","profile":"beta","to":"/Users/lucas/Dev/meu-projeto/AGENTS.md","extra":{"project":"/Users/lucas/Dev/meu-projeto"}}
{"trace_id":"9a0b...","ts":"2026-06-07T12:40:00Z","intent":"update","outcome":"ok","profile":"beta","to":"/Users/lucas/.config/agents-cli/profiles/beta","extra":{"from_version":"v0.3.0","to_version":"v0.3.1"}}

Fields

Field	Meaning
`trace_id`	Unique id correlating the entry with a single command invocation.
`ts`	RFC 3339 timestamp of the operation.
`intent`	The operation: `install`, `project-install`, `update`, `remove`, `project-remove`.
`outcome`	Result of the operation (e.g. `ok`).
`profile`	The profile the operation affected.
`to`	The primary path involved (profile directory or rendered `AGENTS.md`).
`extra`	Operation-specific detail — e.g. `url`, `project`, `from_version` / `to_version`.

The audit.log schema is part of the CLI's public API for SemVer purposes: any breaking change to it is a major bump.

Which operations are logged

Every mutating verb writes an entry. Read-only commands (list, show, doctor, version) do not:

Intent	Written by
`install`	`install --profile` (clone + register a profile)
`project-install`	`install --project` (render an `AGENTS.md` into a project)
`update`	`update --profile` (move a profile to a new release tag)
`remove`	`remove --profile` (unregister a profile)
`project-remove`	`remove --project` (uninstall a project)

Querying with jq

Because it's JSONL, the log streams cleanly into jq and friends:

# Every project installation, pretty-printed
grep '"intent":"project-install"' ~/.local/state/agents-cli/audit.log | jq

# All operations that touched profile "beta"
jq -c 'select(.profile == "beta")' ~/.local/state/agents-cli/audit.log

# Version moves, as "from -> to" lines
jq -r 'select(.intent=="update") | "\(.ts) \(.profile) \(.extra.from_version) -> \(.extra.to_version)"' \
  ~/.local/state/agents-cli/audit.log

To ship the log to an aggregator, tail the file — each line is already a self-contained JSON event.