Getting Started

You need Node.js 24 or newer 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 daily

Or install the llm-usage command:

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

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

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, marks a partial estimate. A dash means the CLI could not resolve cost for that row. See Pricing for the full rules.

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 local month with 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 --days 14

# Group usage by repository
llm-usage session --by-repo

Use Compare for period changes, Session for conversation-level detail, and Trends for a daily series.

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.

If the first report is empty

Run the discovery probe:

llm-usage doctor

Doctor reports the location and health of each source without parsing sessions or 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 support varies by report, so check Output Formats before adding --share to a specialized command.