CLI reference

Every command below exists in the shipped source. Running burn with no arguments prints the same help text, and unknown options are rejected rather than ignored.

Global

proxy and env

burn proxy [--port <port>]
burn env [--port <port>]

burn proxy starts the HTTP proxy on 127.0.0.1, prints the provider routes, prints the OpenAI and Anthropic export lines, and waits until Ctrl+C. The default port is 8787, or the port value in config.json if one is set. --port 0 lets the operating system choose a free port; the chosen port is printed.

burn env prints the same export lines without starting a server. It uses the same port resolution: --port, then config.port, then 8787.

Ports must be whole numbers from 0 to 65535. Anything else is a usage error.

run

burn run -- <command...>

Starts a proxy on a random port, runs the command with OPENAI_BASE_URL and ANTHROPIC_BASE_URL pointing at that proxy, closes the proxy when the command exits, and prints a spend summary for the rows created during the run. The command's exit code is returned.

Everything after -- is passed to the command untouched. If the command is missing, burn exits with an error.

The proxy is temporary. A process that keeps running after burn run returns will not have a proxy to talk to.

ui

burn ui [--port <port>] [--demo]

Serves the dashboard on 127.0.0.1. The default port is 4747. The page is self-contained: one HTML file, one JSON endpoint, no external assets.

--demo creates a temporary home directory, seeds 30 days of made-up traffic, and serves that ledger. It does not touch the ledger in your normal BURN_HOME. The temporary directory is removed when the UI process exits, and the page is marked as demo data.

today, week, month, all

burn today
burn week
burn month
burn all

These take no options. Ranges are calculated in local time:

Each prints the request count, total cost, a row per model, and a total. If any rows have no cost, burn prints a notice with the count.

by-model, by-provider, by-tag

burn by-model [--since <duration>]
burn by-provider [--since <duration>]
burn by-tag [--since <duration>]

Groups the selected window by the named field and prints requests, input, output, cost, and share. --since defaults to all. A row with no tag appears under (untagged).

--since accepts all, or a number followed by a unit:

Examples: --since 24h, --since 7d, --since 30d, --since 12w, --since 90m. The help text calls out 24h, 7d, 30d, and all; the parser accepts any positive integer with one of those units.

watch

burn watch

A live terminal view that refreshes every two seconds. It stays open until Ctrl+C.

add

burn add --model <model> --in <tokens> --out <tokens> [options]

Logs usage by hand. This does not call a provider; it inserts a row directly into the ledger and prices it with the current price book.

If no price is known for the model, the row is stored with no cost and the command says so. Set a price with burn price set, then run burn price recalc.

export

burn export [--json]

Writes every logged request to standard output. The default is CSV. --json writes a JSON array.

CSV columns, in order:

ts,provider,model,tag,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,cost_usd,latency_ms,status,stream

ts is an ISO timestamp. A missing cost is an empty cell. stream is true or false. The JSON objects use the same field names and types.

reset

burn reset --yes

Deletes every row from the requests table. The --yes flag is required; without it, burn refuses and prints an explanation. The database file, config, and cached prices are not removed.

budget

burn budget
burn budget daily <usd> [--block]
burn budget off

With no subcommand, prints the current budget or says that none is set. daily <usd> sets a positive daily limit in US dollars. off removes it.

Without --block, burn warns once per process when today's spend has reached the limit and lets requests continue. With --block, the proxy answers HTTP 429 instead of forwarding the request while today's spend is at or above the limit.

See Budgets for the calculation details.

price

burn price
burn price <filter>
burn price set <model> <in> <out>
burn price unset <model>
burn price update
burn price recalc

With no subcommand, prints the price source, the last fetch time, the number of known models, whether the bundled fallback is in use, whether offline mode is on, and any overrides.

burn price <filter> lists up to 30 stored models whose key contains the filter, case-insensitively. It shows input, output, cache-read, and cache-write prices per 1 million tokens.

burn price set <model> <in> <out> stores an override. The two numbers are USD per 1 million tokens. An override always wins over a fetched price.

burn price unset <model> removes an override.

burn price update fetches the price list now and writes it to prices.json. In offline mode it exits with an error; the cached or bundled list stays in use.

burn price recalc looks at rows whose cost is NULL, prices them with the current book, and fills in the ones it can. It never rewrites a row that already has a cost.

provider

burn provider
burn provider list
burn provider add <name> <url> [openai|anthropic]
burn provider remove <name>

With no subcommand, lists providers with their URL, format, and whether they are built in or yours. provider list does the same. burn providers is an alias for burn provider.

provider add requires a name and a URL. The name must be a single path segment: letters, digits, dots, dashes, and underscores. The URL must start with http:// or https://. The optional format defaults to openai; the other accepted value is anthropic.

provider remove removes a custom provider. Built-in providers are not in config.json, so there is nothing to remove; add a custom provider with the same name to override one.

Duration formats

--since is the only option that takes a duration. It accepts all or <number><unit>, where the unit is m, h, d, or w. A bare number is a usage error. burn today, week, month, and all use fixed local-time ranges and do not accept --since.