CLI reference
Commands, flags, environment variables and exit codes of the tallygraph CLI.
Run any command with npx --yes tallygraph, or install it globally with npm i -g tallygraph. tallygraph help prints the full list.
Usage
| Command | What it does |
|---|---|
collect --token T | Discover local agents, spool their usage and upload it. |
collect --watch | Same, repeated every --interval seconds (default 900). |
collect --dry-run | Validate only. No network, no spool writes. |
read [source] | Print events as JSON lines. Never sends anything. |
collect --file events.jsonl | Upload events you produced yourself (use - for stdin). |
service install | status | uninstall | Manage the background service. |
tap [-- client] | Local proxy that records live API usage. |
agent --team T -- claude [args] | Runs a client through your gateway with a minted key; provider credentials in the shell are not passed on. |
security enroll | collect | status | disable | Opt-in session security reports. See Session security. |
A successful
collect also posts a runtime report: a random install id kept at TALLYGRAPH_STATE_DIR/install-id, plus the versions of the CLI, Node and the agent CLIs in the batch. It feeds the findings on outdated runtimes. A failed report warns and still exits 0.Reading your data back
These commands use a read token, which you also create on the Connectors page. Answers come back in the terminal's language (from LC_ALL or LANG) when a translation exists.
| Command | What it does |
|---|---|
spend [--days N] [--json] | Workspace spend by service. |
findings [--json] | Open findings with estimated savings. |
guard activity [--days N] [--json] | Guard blocks, health and privacy counters (needs an owner read token). |
mcp | Read-only MCP server over stdio with get_spend, get_findings and get_guard_activity. |
Offline audits
These never upload anything.
| Command | What it does |
|---|---|
scan [--staged | --all] | Secret scan of staged or tracked files. Good as a pre-commit hook. |
exposure | Secrets your agents sent to providers in the last 30 days. |
trifecta | Sessions that mixed private data, untrusted content and a way out. |
navwaste | How Claude sessions split between navigation, edits and commands. |
Environment variables
| Variable | Used for |
|---|---|
TALLYGRAPH_WRITE_TOKEN | Write token for collect and tap, instead of --token. |
TALLYGRAPH_READ_TOKEN | Read token for spend, findings and mcp. |
TALLYGRAPH_ENDPOINT | Custom ingest or app URL. Defaults to www.tallygraph.dev. |
TALLYGRAPH_STATE_DIR | Spool location. Defaults to ~/.tallygraph. |
Exit codes of collect
| Code | Meaning |
|---|---|
| 0 | Everything delivered. |
| 1 | Unexpected error. |
| 2 | The API rejected the request. Rows kept in the spool. |
| 3 | Spool could not be opened or is full. |
| 4 | Token invalid, revoked or expired. Rows kept in the spool. |
| 5 | Retries exhausted. Rows kept; run again to resume. |
Sending your own events
Anything that can write JSON lines can report usage. Each line is one event; repeated external_id values are ignored, so you can resend safely.
events.jsonl
{"external_id":"run-42-call-1","service_slug":"anthropic","model":"claude-sonnet-5-5","input_tokens":1200,"output_tokens":340,"occurred_at":"2026-11-02T18:00:00Z"}terminal
tallygraph collect --file events.jsonl --dry-run # check first tallygraph collect --file events.jsonl --token tg_xxxxxxxx