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 into the requests DB.
`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: spend, waste rate, error spend, cost/outcome.
`burnlens outcome`	Record business outcomes to get 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 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 login`	Authenticate with burnlens.app and enable cloud sync.
`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

Cost per merged PR on a repository, using the gh CLI to resolve outcomes:

burnlens outcome derive     # merged PRs -> outcomes
burnlens outcome show       # cost per accepted outcome

Both are idempotent and safe on a schedule: outcome ids are derived deterministically from the repo and PR number, so re-running only adds newly-closed PRs.

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 hard caps. 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 & hard caps — Daily key caps, team and customer budgets, virtual keys, downgrade routing.
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.