Choose a Report

Start with a question, then narrow the result with source, model, provider, project, or date filters. If you have not run the CLI yet, follow Getting Started.

Tokens and cost over time

Question	Command	Default window
What did I spend today and this month?	`llm-usage`	Today, 7 days, month to date
Which hours were busy today?	`llm-usage hourly`	Today
How much did I use each day?	`llm-usage daily`	Last 7 days
How did the weeks or months add up?	`llm-usage weekly` or `llm-usage monthly`	Last 8 weeks, or full history
What changed from last month?	`llm-usage compare`	Month to date vs. the same days
Is usage rising or falling?	`llm-usage trends --metric tokens --last 14`	Last 30 days
What did the year look like?	`llm-usage wrapped`	The current year

--last N reports the last N periods of the command, counting the current one, and --all reports full history. Every report that reads usage accepts --all; it changes nothing where the default is already the full history, and summary, compare and wrapped ignore it. Each question links to the guide for its command, which lists the limits.

# Limit the report to one source and one calendar month
llm-usage monthly --source codex --since 2026-09-01 --until 2026-09-30

Projects and sessions

Question	Command	Default window
Which projects cost the most?	`llm-usage projects`	Full history
Which conversations cost the most?	`llm-usage session --top 10`	Full history
Why did this session cost so much?	`llm-usage session --id <id> --timeline`	Full history
Which tools do my agents call, and which fail?	`llm-usage tools`	Last 7 days
Which sessions push the context window?	`llm-usage context --by-session`	Last 7 days
How does usage compare with commits in one repo?	`llm-usage efficiency monthly`	Full history

Most reports also take --repo to count some projects only, and the usage reports split rows by project with --by-repo. Efficiency ratios depend on project attribution and Git history; they do not measure code quality or developer productivity.

Plans and models

Question	Command	Default window
How much of my 5-hour window have I used?	`llm-usage blocks`	Last 7 days
Would the API have cost more than my subscription?	`llm-usage value`	Full history
What would my usage cost on another model?	`llm-usage optimize monthly --provider openai --candidate-model gpt-4.1`	Full history
Which price does a model name get?	`llm-usage pricing claude-sonnet-4-5`	Reads no usage

Optimize prices your observed token mix against candidate models. It does not run the models or predict their output quality, latency, or future token usage.

Need	Command	Guide
An interactive HTML report	`llm-usage monthly --share`	Interactive report
An aggregated report for a script	`llm-usage daily --json`	Output formats
A table for a document	`llm-usage daily --markdown`	Output formats
Individual normalized events	`llm-usage events --format jsonl`	Events export
Events for a spreadsheet	`llm-usage events --format csv`	Events export
A line for a status bar	`llm-usage statusline`	Status line
The installed report’s schema	`llm-usage schema usage`	JSON contracts

Report JSON uses a versioned envelope. Event JSONL is one event per line without that envelope. Diagnostics go to stderr, so you can redirect report data safely. Output formats lists which formats each command supports.

Discovery and maintenance

# Inspect source locations and ledger health
llm-usage doctor

# Show which config-file values are active
llm-usage config show

# Preview removal of departed files suppressed as moves or duplicates
llm-usage prune --suppressed

Use Doctor when data is missing, Configuration to save defaults, and Caching and history to understand the event ledger. prune is a dry run unless you pass --apply; applying age-based pruning permanently removes selected retained history.