CLI reference

The top-level surface as of 2026-08-16, taken from burnlens --help. Every command takes --help of its own, which is authoritative for your installed version.

Where things live

What	Path
Database	`~/.burnlens/burnlens.db`
Config (YAML, not TOML)	`$BURNLENS_CONFIG_PATH`, then `./burnlens.yaml`, `./burnlens.yml`, then `~/.burnlens/config.yaml`
Write-ahead log	`~/.burnlens/wal.jsonl`
Dead letter queue	`~/.burnlens/wal_dlq.jsonl`
Proxy	`127.0.0.1:8420`

There is no burnlens --version. Use pip show burnlens to find out what you have installed.

Collect

Command	What it does
`burnlens scan`	Import coding-agent session costs from disk, then derive merged-PR outcomes when gh is present.
`burnlens start`	Start the BurnLens proxy server.
`burnlens run`	Run a child command with auto-tagged git context.

Look at spend

Command	What it does
`burnlens top`	Live API traffic viewer with auto-refresh.
`burnlens ui`	Open the dashboard in the default browser.
`burnlens report`	Generate and print (or email) a cost summary report.
`burnlens repos`	Show top 20 repos by cost over the lookback window.
`burnlens prs`	Show top 20 PRs by cost over the lookback window.
`burnlens devs`	Show top 20 developers by cost over the lookback window.
`burnlens runs`	Group spend into runs and their steps.
`burnlens export`	Export request data to CSV.

Find waste

Command	What it does
`burnlens analyze`	Run waste detectors and print findings.
`burnlens findings`	Persisted waste findings and their lifecycle.
`burnlens economics`	Top-line runtime economics, then burnlens recommend for the switch.
`burnlens outcome`	Record, correct, and inspect business outcomes and cost per accepted outcome.
`burnlens recommend`	Analyse usage patterns and suggest cheaper model alternatives.

Control spend

Command	What it does
`burnlens budgets`	Show per-team budget status for the current month.
`burnlens customers`	Show per-customer spend and budget status for the current month.
`burnlens controls`	Show configured budget scopes, failure policy, concurrency guarantees, and known ceilings.
`burnlens key`	Register API keys for per-key daily caps.
`burnlens keys`	Show today's spend per API-key label against its daily cap.
`burnlens vkey`	Issue virtual keys (gateway): per-team budget + model allowlist.
`burnlens routing`	Show downgrade routing activity.

Operate

Command	What it does
`burnlens cloud connect`	Connect local cost metadata to a BurnLens Cloud workspace. Prompt bodies are never uploaded.
`burnlens login`	Authenticate with burnlens.app and enable cloud sync (same as cloud connect).
`burnlens sync`	Manually trigger cloud sync or check sync status.
`burnlens doctor`	Run system health checks on proxy, database, and providers.
`burnlens pricing`	Show the bundled model pricing table ($/1M tokens), or export it as CSV.
`burnlens check-otel`	Verify connectivity to the OpenTelemetry collector.
`burnlens wal`	Manage the Write-Ahead Log (WAL) and Dead Letter Queue (DLQ).

Common sequences

First cost number, from history that already exists:

pip install burnlens
burnlens scan
burnlens repos

Need the same economics across developers? Create a workspace, then:

burnlens cloud connect
burnlens sync --now

Cost per merged PR: burnlens scan derives outcomes for the current checkout when gh is installed, or prints that it is missing. Re-run derive later, or from another checkout:

burnlens outcome derive                         # all closed PRs, paginated (needs gh)
burnlens outcome derive --since 2026-01-01 --until 2026-02-01
burnlens outcome show       # cost per accepted outcome
burnlens outcome correct ticket-1 --status accepted --reason "reopened and fixed"
burnlens outcome history ticket-1

Derivation is idempotent and safe on a schedule: outcome ids are derived deterministically from the canonical repository and PR number, so re-running only adds newly-closed PRs. The command reports its date scope and whether the import was complete; --limit is an explicit, incomplete subset. A genuine status change is corrected in place, with the prior state retained in outcome history rather than counted again.

Meter and cap production traffic:

burnlens start
export OPENAI_BASE_URL=http://127.0.0.1:8420/proxy/openai
burnlens key register --label prod-openai --provider openai
burnlens keys

Find out why nothing is showing up:

burnlens doctor

Flags and behaviour per area: scanning, proxy and tagging, budgets and enforcement. Errors and their fixes live in troubleshooting.

All documentation

Overview & install — What BurnLens is, how to install it, and which of the two entry points you want.
Scanning coding agents — Import Claude Code, Cursor, Codex and Gemini CLI cost history from local logs.
Proxy & tagging — Route production API traffic through the local proxy and attribute it with tags.
Budgets & enforcement — Daily key caps, control scope, concurrency guarantees, virtual keys, downgrade routing.
Cost evidence — Cost Confidence, Outcome Coverage and Verified Savings — how much of a number BurnLens can prove.
Known limitations — Where each figure stops being authoritative, stated plainly.
CLI reference — Every burnlens command, and where the config file and database live.

Something here wrong or missing? Open an issue or email support@burnlens.app.