Output Formats

Terminal (default)

llm-usage daily

Terminal output includes:

• boxed report header
• semantic header colors and source-aware row styling
• summary-row emphasis for combined and grand totals
• diagnostics on stderr
• data table on stdout

JSON

llm-usage daily --json

Use for scripting and automation pipelines.

Markdown

llm-usage daily --markdown

Use for docs, changelogs, and issue/PR reporting.

Usage report tables rank per-period models by total tokens so the dominant models appear first in both terminal and Markdown output.

Share SVG

Generate a dark-themed share image:

# Usage reports (daily, weekly, or monthly)
llm-usage monthly --share
llm-usage daily --share
llm-usage weekly --share

# Efficiency (monthly only)
llm-usage efficiency monthly --repo-dir /path/to/repo --share

# Optimize (monthly only)
llm-usage optimize monthly --provider openai --candidate-model gpt-4.1 --share

--share writes an SVG file to the current directory:

• Usage reports: usage-{granularity}-share.svg (stacked area chart by source)
• Efficiency: efficiency-monthly-share.svg (commit bars + $/commit line)
• Optimize: optimize-monthly-share.svg (savings % heatmap)

All share images use a dark theme designed for social media sharing.

Efficiency reports

llm-usage efficiency daily
llm-usage efficiency weekly --repo-dir /path/to/repo --json
llm-usage efficiency monthly --repo-dir /path/to/repo --share

Efficiency outputs include usage totals, Git outcomes (Commits, +Lines, -Lines, ΔLines), and derived ratios.

Usage values are repo-attributed: only usage events mapped to the selected repository root are included.

Columns:

• Input, Output, Reasoning, Cache Read, Cache Write, Total, Cost come from repo-attributed usage events.
• Commits, +Lines, -Lines, ΔLines come from local Git shortstat outcomes for the configured Git author.
• Tokens/Commit = (Input + Output + Reasoning) / Commits (excludes cache read/write tokens).
• $/Commit = Cost / Commits.
• $/1k Lines = Cost / (ΔLines / 1000).
• Commits/$ = Commits / Cost (only when Cost > 0).

Efficiency period rows are emitted only when both Git outcomes and repo-attributed usage signal exist for that period. When a denominator is zero, derived values render as - in terminal/markdown and are omitted in JSON. When pricing is incomplete, affected USD values are prefixed with ~ in terminal/markdown.

Usage filters (--source, --provider, --model, source-path overrides) also affect commit attribution: only commit days with matching repo-attributed usage events are counted. --provider scopes by billing entity (for example, openai-codex is normalized to openai).

For deeper semantics (repo attribution, scope behavior, and interpretation guidance), see the Efficiency page.

--share is monthly-only for efficiency (see Share SVG above).

Optimize reports

llm-usage optimize monthly --provider openai --candidate-model gpt-4.1 --candidate-model gpt-5-codex
llm-usage optimize weekly --provider openai --candidate-model gpt-4.1,gpt-5-codex --top 1 --json
llm-usage optimize monthly --provider openai --candidate-model gpt-4.1 --candidate-model gpt-5-codex --share

Optimize output contains baseline and candidate rows per period:

• baseline rows: observed token totals and baseline cost
• candidate rows: hypothetical cost on each candidate model, savings delta, and notes for missing pricing/incomplete baselines

For JSON and Markdown, stdout includes only the report body; diagnostics and warnings remain on stderr.

--share is monthly-only for optimize (see Share SVG above).

Trends reports

llm-usage trends
llm-usage trends --metric tokens --days 7
llm-usage trends --by-source --json

• Default terminal output renders a daily trend chart.
• --json emits structured trend series (metric, dateRange, totalSeries, optional sourceSeries).
• Diagnostics stay on stderr.
• Markdown is not supported for this command.

Per-model columns

Detailed multiline metrics per model:

llm-usage monthly --per-model-columns
llm-usage monthly --markdown --per-model-columns

When model breakdowns are present, rows are ordered by descending total tokens before the final Σ TOTAL line.

stdout/stderr behavior

• stdout: report body (terminal, json, or markdown)
• stderr: diagnostics (session summary, parse failures, skipped rows, pricing source)