Command reference — index¶
The program name is agent-trace (short alias at when installed). Invoking agent-trace with no subcommand prints top-level help and exits 0.
Global options¶
| Option | Purpose |
|---|---|
--version |
Print version string and exit. |
There is no global --verbose flag today; individual commands print human-readable diagnostics to stderr on error.
Command matrix¶
| Command | Summary |
|---|---|
| init | Initialize tracing for the current git project (zero-prompt). |
| doctor | Health check: hooks, config, storage, remotes, optional tools. |
| status | Git-style overview: project id, paths, counts, sync/hook hints. |
| reset | Interactive reconfiguration wizard. |
| config | show | set | reset for persisted configuration. |
| hooks | setup-global | remove-global | status for agent hooks. |
| record | Read one JSON trace event from stdin (hook entrypoint). |
| commit-link | Post-commit: link commit, build ledger. |
| rewrite-ledger | Post-rewrite: remap ledger SHAs. |
| viewer | Launch file viewer UI. |
| blame | Ledger-only attribution for a file. |
| context | Conversation snippets / full transcript for AI ranges. |
| rule | add | remove | show | list prebuilt agent rules. |
| set | set globaluser <token>. |
| remove | remove globaluser. |
| remote | Named HTTP remotes (add, list, …). |
| push | Upload local artifacts. |
| pull | Download remote artifacts. |
| sync | Push then pull. |
| projects | List registry rows or projects show <id>. |
| adopt | Register repo, print project_id. |
| project create | Register a project on a remote service (POST /api/v1/projects). |
| notes | Git notes on refs/notes/agent-trace. |
| summary | Pluggable transcript summarization. |
Reading guide¶
- Human operators — follow Getting started then skim Concepts for mental model.
- Automation / CI — prefer
--jsonwhere available (config show,blame,context) andblame --require-attributionwhen enforcing provenance. - Authors of wrappers — rely on
--helpon each subcommand for argparse text; this site expands purpose and edge cases.
Conventions used in this reference¶
<arg>— required placeholder.[optional]— may be omitted.- Exit codes —
0success unless a command documents non-zero (for exampleblame --require-attribution).