Getting Started

You need Node.js 22.16+ or 24+ (not 23), or Bun 1.4+, and session data from at least one supported source. The CLI discovers standard source locations, so most first runs need no configuration.

1. Run the CLI

Try it without installing:

npx --yes llm-usage-metrics@latest

Or install the llm-usage command (llm-usage-metrics is an alias for the same CLI):

npm install -g llm-usage-metrics
llm-usage

With Bun, bunx --bun llm-usage-metrics@latest runs the CLI on Bun rather than Node. Every feature works on Bun, including the SQLite event store, and repeat runs start faster; CI checks that its reports match Node’s.

With no command, llm-usage prints cost and tokens for today, the last 7 days, and month to date, plus the source with the highest cost in each period, followed by your streaks and a past-year activity heatmap. Run llm-usage daily for one row per day and source.

The first run parses matching session files, stores normalized events in a local SQLite ledger, and loads pricing. Later runs can reuse unchanged files from the ledger.

2. Read the table

llm-usage daily covers the last 7 days in your reporting timezone; add --since YYYY-MM-DD or --all for older usage. Each period contains one row per source. A combined row appears when the period includes more than one source, and the final ALL row totals the full range.

Token columns keep the buckets supplied by each source:

• Input, Output, and Reasoning
• Cache Read and Cache Write
• Total, using the source adapter’s normalized total

Cost may come from the source or from LiteLLM pricing. A tilde, such as ~$4.82, means only some contributing events have a resolved cost. A dash means the CLI could not resolve cost for that row. See Pricing for the full rules.

Use an offline report

After installation, skip both pricing refreshes and startup update checks with:

LLM_USAGE_SKIP_UPDATE_CHECK=1 llm-usage daily --pricing-offline

The CLI uses cached or bundled rates. Downloading the package with npm or npx still requires network access. See Privacy for network behavior.

3. Scope the result

Use calendar ranges and filters to answer a narrower question:

# A calendar month in your reporting timezone
llm-usage monthly --since 2026-06-01 --until 2026-06-30

# Only Codex and Claude Code sessions
llm-usage monthly --source codex,claude

# Sessions billed through OpenAI
llm-usage monthly --provider openai

# A model name or substring
llm-usage monthly --model codex

--source describes where the event came from. --provider describes the billing entity behind the model. A Codex session can therefore have source=codex and provider=openai.

4. Choose a closer view

# Compare the current month to date with the same days of the previous month
llm-usage compare

# Rank conversations by cost
llm-usage session --top 10

# Chart the last 14 local days
llm-usage trends --metric tokens --last 14

# Rank projects (recorded working directories) by cost
llm-usage projects

The report chooser covers every command by question. Use Compare for period changes, Session for conversation-level detail, Trends for a daily series, and Projects for cost per project.

5. Save your defaults when you need them

llm-usage config init

The command writes a commented TOML file with the current defaults and a JSON Schema directive for editor validation. Common reasons to edit it include:

• your sessions live outside a tool’s default directory
• you want a fixed reporting timezone
• you prefer offline pricing or quieter diagnostics

CLI flags override environment variables, which override the config file. Configuration lists every key and its matching flag.

6. Turn on tab completion

llm-usage completion <shell> prints a completion script for bash, zsh, or fish. It completes commands, flags, source ids after --source, and file paths after the directory flags, for both llm-usage and llm-usage-metrics:

# bash: add to ~/.bashrc
source <(llm-usage completion bash)

# zsh: add to ~/.zshrc, after compinit
source <(llm-usage completion zsh)

# fish: one file per bin name, since fish loads completions by command name
for name in llm-usage llm-usage-metrics; llm-usage completion fish > ~/.config/fish/completions/$name.fish; end

Every command’s --help ends with a few examples.

Using more than one machine?

Reports can include usage from your other machines over ssh. Install llm-usage-metrics there and make sure ssh logs in without a prompt, then add the machine by name:

llm-usage machine add laptop

See Multiple machines for destinations and options.

If the first report is empty

Run the discovery probe:

llm-usage doctor

Doctor reports where each source looks and whether its newest files contain readable usage, without loading pricing. Probe one source or give it an explicit path when needed:

llm-usage doctor --source codex
llm-usage doctor --source claude --claude-dir /path/to/.claude/projects

The Data Sources pages list default locations and override flags. Troubleshooting covers parse failures, missing pricing, and event-store issues.

Export the result

llm-usage daily --json
llm-usage daily --markdown
llm-usage monthly --share

Report data goes to stdout; diagnostics stay on stderr. This separation keeps JSON and Markdown safe to redirect into a file or pipeline.

--share writes an interactive HTML report to the current directory and opens it in your browser; --no-open only writes it. The page loads nothing from the network and can filter the report by source, model, project and machine. It works on summary, daily, weekly, monthly, compare, trends, wrapped, efficiency and optimize. See Interactive report.