CLI Reference
Command structure
Section titled “Command structure”llm-usage <command> [options]Commands:
dailyweeklymonthlycompareefficiency <daily|weekly|monthly>optimize <daily|weekly|monthly>trendssessionwrappedeventsdoctorpruneconfig <init|show|path>schema
Options
Section titled “Options”Generated from root + command help output.
| Option | Short | Argument | Description |
|---|---|---|---|
--amp-dir |
- | <path> |
Path to Amp threads directory |
--antigravity-dir |
- | <path> |
Path to Antigravity conversations directory |
--apply |
- | - | Delete selected departed files and vacuum the event store (prune only) |
--by-repo |
- | - | Group usage by repository root instead of by session (session only) |
--by-source |
- | - | efficiency: Include per-source usage rows under each period; trends: Render one sparkline row per source instead of a single combined chart |
--candidate-model |
- | <name> |
Candidate model for counterfactual pricing (repeatable or comma-separated) (optimize only) |
--claude-dir |
- | <path> |
Path to Claude projects directory |
--cline-dir |
- | <path> |
Path to Cline tasks directory |
--codex-dir |
- | <path> |
Path to .codex sessions directory |
--copilot-dir |
- | <path> |
Path to GitHub Copilot OTEL directory |
--days |
- | <n> |
Trailing local calendar days to chart; defaults to 30 when no date flags are provided (trends only) |
--departed-before |
- | <YYYY-MM-DD> |
Select departed files whose newest event timestamp is strictly before this UTC date (prune only) |
--droid-dir |
- | <path> |
Path to Droid sessions directory |
--force |
- | - | Overwrite an existing config file (config only) |
--format |
- | <name> |
Export format: jsonl | csv (default: “jsonl”) (events only) |
--gemini-dir |
- | <path> |
Path to .gemini directory |
--goose-db |
- | <path> |
Path to Goose SQLite DB |
--history |
- | - | include usage from files that no longer exist on disk (from the local event store) (daily, weekly, monthly, compare, efficiency, optimize, trends, session, wrapped, events only) |
--id |
- | <session-id> |
Show only sessions whose id contains the value (case-insensitive; repeatable or comma-separated) (session only) |
--ignore-pricing-failures |
- | - | Continue without estimated costs when pricing cannot be loaded (daily, weekly, monthly, compare, efficiency, optimize, trends, session, wrapped, events only) |
--include-merge-commits |
- | - | Include merge commits in Git outcome metrics (efficiency only) |
--json |
- | - | Render output as JSON |
--kilocode-dir |
- | <path> |
Path to KiloCode tasks directory |
--kimi-dir |
- | <path> |
Path to Kimi sessions directory |
--list |
- | - | List available schema names (schema only) |
--markdown |
- | - | Render output as Markdown table (daily, weekly, monthly, compare, efficiency, optimize, trends, session, wrapped only) |
--metric |
- | <name> |
Trend metric: cost | tokens (default: “cost”) (trends only) |
--model |
- | <name> |
Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) (daily, weekly, monthly, compare, efficiency, optimize, trends, session, wrapped, events only) |
--openclaw-dir |
- | <path> |
Path to OpenClaw agents directory |
--opencode-db |
- | <path> |
Path to OpenCode SQLite DB |
--per-model-columns |
- | - | Render per-model metrics as multiline aligned table columns (terminal/Markdown) (usage reports only) |
--pi-dir |
- | <path> |
Path to .pi sessions directory |
--pricing-offline |
- | - | Use cached LiteLLM pricing only (no network fetch) (daily, weekly, monthly, compare, efficiency, optimize, trends, session, wrapped, events only) |
--pricing-overrides |
- | <path> |
Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) (daily, weekly, monthly, compare, efficiency, optimize, trends, session, wrapped, events only) |
--pricing-url |
- | <url> |
Override LiteLLM pricing source URL (daily, weekly, monthly, compare, efficiency, optimize, trends, session, wrapped, events only) |
--provider |
- | <name> |
Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) (daily, weekly, monthly, compare, efficiency, optimize, trends, session, wrapped, events only) |
--quiet |
- | - | Suppress informational stderr output (warnings still print) |
--qwen-dir |
- | <path> |
Path to Qwen projects directory |
--repo-dir |
- | <path> |
Path to repository for Git outcome metrics (efficiency only) |
--roocode-dir |
- | <path> |
Path to RooCode tasks directory |
--share |
- | - | Write a share SVG image to the current directory (daily, weekly, monthly, compare, efficiency, optimize, trends, wrapped only) |
--since |
- | <YYYY-MM-DD> |
Inclusive start date filter (daily, weekly, monthly, compare, efficiency, optimize, trends, session, events only) |
--source |
- | <name> |
Filter by source id (repeatable or comma-separated, supported sources (16): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity) |
--source-dir |
- | <source-id=path> |
Override source directory for directory-backed sources (repeatable) |
--suppressed |
- | - | Select departed files that –history already suppresses (prune only) |
--timezone |
- | <iana> |
Timezone for bucketing (default: system timezone) (daily, weekly, monthly, compare, efficiency, optimize, trends, session, wrapped, events only) |
--top |
- | <n> |
optimize: Show only the top N cheapest candidates (positive integer); session: Show only the top N rows by cost (default 20; 0 shows all) |
--until |
- | <YYYY-MM-DD> |
Inclusive end date filter (daily, weekly, monthly, compare, efficiency, optimize, trends, session, events only) |
--vs-since |
- | <date> |
Inclusive start date for the baseline comparison window (compare only) |
--vs-until |
- | <date> |
Inclusive end date for the baseline comparison window (compare only) |
--year |
- | <YYYY> |
Year to recap (2020-2100; defaults to current local year) (wrapped only) |
--help |
-h |
- | display help for command |
--version |
-V |
- | output the version number |
Examples
Section titled “Examples”llm-usage dailyllm-usage daily --source-dir pi=/tmp/pi-sessions --source-dir gemini=/tmp/.gemini --source-dir droid=/tmp/droid-sessions --source-dir openclaw=/tmp/openclaw-agentsllm-usage daily --jsonllm-usage daily --markdownllm-usage weekly --timezone Europe/Parisllm-usage monthly --since 2026-01-01 --until 2026-01-31llm-usage monthly --source opencode --opencode-db /path/to/opencode.db --jsonllm-usage monthly --source gemini --gemini-dir /path/to/.geminillm-usage monthly --history --pricing-offlinellm-usage monthly --source droid --droid-dir /path/to/.factory/sessionsllm-usage monthly --sharellm-usage comparellm-usage compare --since 2026-06-01 --until 2026-06-30 --vs-since 2026-05-01 --vs-until 2026-05-31llm-usage efficiency weekly --repo-dir /path/to/repo --jsonllm-usage efficiency monthly --sharellm-usage optimize monthly --provider openai --candidate-model gpt-4.1 --candidate-model gpt-5-codex --jsonllm-usage optimize monthly --provider openai --candidate-model gpt-4.1 --candidate-model gpt-5-codex --sharellm-usage trendsllm-usage trends --metric tokens --days 7llm-usage trends --by-source --jsonllm-usage sessionllm-usage session --top 5 --jsonllm-usage session --id 486cllm-usage session --by-repo --top 5llm-usage session --markdownllm-usage wrappedllm-usage wrapped --year 2026 --sharellm-usage wrapped --year 2026 --jsonllm-usage events --format jsonl > events.jsonlllm-usage events --format csv --since 2026-01-01llm-usage doctorllm-usage doctor --jsonllm-usage prune --suppressedllm-usage prune --departed-before 2026-01-01 --apply