Documentation
llm-usage-metrics reads session data created by supported AI coding tools and converts it into one normalized usage history. You can review token volume, estimate cost, find expensive sessions, compare periods, and export the results. The CLI parses session content on your machine.
Run your first report
Section titled “Run your first report”npx --yes llm-usage-metrics@latestThe command prints cost and tokens for today, the last 7 days, and month to date. It discovers supported sources in their default locations. Use llm-usage doctor if the report finds no data, or create a config file when your sessions live elsewhere.
llm-usage doctorllm-usage config initPick the report by question
Section titled “Pick the report by question”Use the report chooser for commands, defaults, and links to each guide.
| Question | Command |
|---|---|
| How many tokens and dollars did I use? | daily, weekly, monthly, hourly |
| Which projects cost the most? | projects |
| How did this period change from the last one? | compare |
| Which conversations used the most? | session |
| How is usage moving day by day? | trends |
| How is usage spread over 5-hour subscription windows? | blocks |
| Is my subscription worth its price at API rates? | value |
| How does repo-attributed usage line up with Git activity? | efficiency |
| What would the same token mix cost on another model? | optimize |
| How did the year add up? | wrapped |
| How does a model name get its price? | pricing <model...> |
| What goes in my status bar? | statusline |
| Which sources can the CLI see? | doctor |
| Which departed files can I remove from the event ledger? | prune |
Add --share to summary, daily, weekly, monthly, compare, trends, wrapped, efficiency or optimize to write an interactive HTML report you can filter by source, model, project and machine.
How the CLI handles your numbers
Section titled “How the CLI handles your numbers”Source adapters normalize input, output, reasoning, cache read, and cache write tokens at the file boundary. The pricing engine keeps an explicit source cost when one exists. Otherwise, it estimates cost from LiteLLM pricing.
Reports show the difference:
$12.34means every contributing event has a resolved cost.~$12.34means the known cost is partial.-means the CLI could not price any contributing event.
The bundled pricing snapshot lets the first report run offline. An online run may refresh the pricing cache from LiteLLM. Pricing requests never include session content.
What stays on your machine
Section titled “What stays on your machine”The CLI reads local session files and local Git history. It writes its event ledger under your platform data directory and its caches under your platform cache directory. Two optional network requests remain separate from your usage data:
- a cached npm version check at startup
- a LiteLLM pricing refresh when the pricing cache is stale
Use --pricing-offline and LLM_USAGE_SKIP_UPDATE_CHECK=1 when you want a report with no network requests.
If you add other machines, the CLI also uses your ssh to fetch their usage events. See Privacy for every network request.