CLI Reference
Command structure
Section titled “Command structure”llm-usage <command> [options]Commands:
summaryhourlydailyweeklymonthlyprojectscompareefficiency <daily|weekly|monthly>optimize <daily|weekly|monthly>trendssessiontoolscontextblocksvaluewrappedeventspricing <model...>statuslinedoctorpruneconfig <init|show|path>machine <add|list|remove|export>syncschemacompletion
Command help
Section titled “Command help”Open a command to see its supported flags and defaults. Flags in the option index below are not available on every command.
llm-usage summary
Usage: llm-usage summary [options]
Show cost and tokens for today, the last 7 days, and month to date, plusactivity streaks (default command)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --share Write an interactive HTML report to the current directory --no-open With --share, write the report without opening it --redact With --share, label projects project-N, machines machine-N and local or path-shaped models model-N --all No effect: the summary always covers today, the last 7 days and month to date --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage hourly
Usage: llm-usage hourly [options]
Show hourly usage report (today unless --last, --since, --until, or --all)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --per-model-columns Render per-model metrics as multiline aligned table columns (terminal/markdown) --last <n> Report the last N days hour by hour (1-31), counting today --all Report every hour instead of today --compact Abbreviate token counts and hide the Reasoning and Cache Write columns (terminal/markdown) --no-cost Leave cost out of the table, e.g. for screenshots --by-machine Split each source row by the machine its usage came from --by-repo Split each source row by project (the working directory the tool recorded) --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage daily
Usage: llm-usage daily [options]
Show daily usage report (last 7 days unless --last, --since, --until, or --all)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --per-model-columns Render per-model metrics as multiline aligned table columns (terminal/markdown) --share Write an interactive HTML report to the current directory --no-open With --share, write the report without opening it --redact With --share, label projects project-N, machines machine-N and local or path-shaped models model-N --all Report every day instead of the last 7 days --last <n> Report the last N days, counting the current day --compact Abbreviate token counts and hide the Reasoning and Cache Write columns (terminal/markdown) --no-cost Leave cost out of the table and share report, e.g. for screenshots --by-machine Split each source row by the machine its usage came from --by-repo Split each source row by project (the working directory the tool recorded) --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage weekly
Usage: llm-usage weekly [options]
Show weekly usage report (week starts Monday; last 8 weeks unless --last,--since, --until, or --all)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --per-model-columns Render per-model metrics as multiline aligned table columns (terminal/markdown) --share Write an interactive HTML report to the current directory --no-open With --share, write the report without opening it --redact With --share, label projects project-N, machines machine-N and local or path-shaped models model-N --all Report every week instead of the last 8 weeks --last <n> Report the last N weeks, counting the current week --compact Abbreviate token counts and hide the Reasoning and Cache Write columns (terminal/markdown) --no-cost Leave cost out of the table and share report, e.g. for screenshots --by-machine Split each source row by the machine its usage came from --by-repo Split each source row by project (the working directory the tool recorded) --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage monthly
Usage: llm-usage monthly [options]
Show monthly usage report
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --per-model-columns Render per-model metrics as multiline aligned table columns (terminal/markdown) --share Write an interactive HTML report to the current directory --no-open With --share, write the report without opening it --redact With --share, label projects project-N, machines machine-N and local or path-shaped models model-N --all Report the full history (the default without date flags) --last <n> Report the last N months, counting the current month --compact Abbreviate token counts and hide the Reasoning and Cache Write columns (terminal/markdown) --no-cost Leave cost out of the table and share report, e.g. for screenshots --by-machine Split each source row by the machine its usage came from --by-repo Split each source row by project (the working directory the tool recorded) --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage projects
Usage: llm-usage projects [options]
Show cost, tokens, events, active days and top models per project (the workingdirectory the tool recorded), costliest first (full history unless --last,--since, or --until)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --granularity <period> Add rows per period and project (choices: "daily", "weekly", "monthly") --top <n> Show only the top N projects by cost (default 10; 0 shows all) --last <n> Report the last N months, counting the current month --all Report the full history (the default without date flags) --compact Abbreviate token counts and leave out minor columns (terminal/markdown) --no-cost Leave cost out of the table, e.g. for screenshots --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage compare
Usage: llm-usage compare [options]
Compare usage and cost between two date windows
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --share Write an interactive HTML report to the current directory --no-open With --share, write the report without opening it --redact With --share, label projects project-N, machines machine-N and local or path-shaped models model-N --vs-since <date> Inclusive start date for the baseline comparison window --vs-until <date> Inclusive end date for the baseline comparison window --by-repo Also compare each project (the working directory the tool recorded) --all No effect: compare reads its two windows from the date flags --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage efficiency <daily|weekly|monthly>
Usage: llm-usage efficiency [options] <granularity>
Show efficiency report by correlating usage metrics with local Git outcomes
Arguments: granularity Report period (choices: "daily", "weekly", "monthly")
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --share Write an interactive HTML report to the current directory --no-open With --share, write the report without opening it --redact With --share, label projects project-N, machines machine-N and local or path-shaped models model-N --repo-dir <path> Path to repository for Git outcome metrics --include-merge-commits Include merge commits in Git outcome metrics --by-source Include per-source usage rows under each period --all Report the full history (the default without date flags) --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching. It filters usage events; --repo-dir picks the Git repository for outcomes -h, --help display help for commandllm-usage optimize <daily|weekly|monthly>
Usage: llm-usage optimize [options] <granularity>
Show counterfactual pricing report for candidate model(s)
Arguments: granularity Report period (choices: "daily", "weekly", "monthly")
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --share Write an interactive HTML report to the current directory --no-open With --share, write the report without opening it --redact With --share, label projects project-N, machines machine-N and local or path-shaped models model-N --candidate-model <name> Candidate model for counterfactual pricing (repeatable or comma-separated) --top <n> Show only the top N cheapest candidates (positive integer) --all Report the full history (the default without date flags) --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage trends
Usage: llm-usage trends [options]
Show daily cost or token usage trends
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --share Write an interactive HTML report to the current directory --no-open With --share, write the report without opening it --redact With --share, label projects project-N, machines machine-N and local or path-shaped models model-N --last <n> Chart the last N local calendar days, counting today; defaults to 30 when no date flags are provided --days <n> Alias of --last --all Chart every day since the first usage instead of the last 30 days --metric <name> Trend metric: cost | tokens | active-hours (default: "cost") --by-source Render one sparkline row per source instead of a single combined chart --by-repo Render one sparkline row per project (the working directory the tool recorded); not with --by-source --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage session
Usage: llm-usage session [options]
Show usage grouped by conversation session
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --top <n> Show only the top N rows by cost (default 20; 0 shows all) --id <session-id> Show only sessions whose id contains the value (case-insensitive; repeatable or comma-separated) --by-repo Group usage by project (the working directory the tool recorded) instead of by session --timeline With --id naming one session: list its requests in time order with a running cost, between its tool calls and turns --all Report the full history (the default without date flags) --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage tools
Usage: llm-usage tools [options]
Show tool calls per tool with errors, error rate and sessions, most calls first,from claude, codex and pi sessions (last 7 days unless --last, --since, --until,or --all)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --top <n> Show only the top N tools by calls (default 20; 0 shows all) --by-source Split each tool row by source --by-repo Split each tool row by project (the working directory the tool recorded) --last <n> Report the last N days, counting today (default 7) --all Report every tool call on disk instead of the last 7 days --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Keeps the tool calls of sessions whose usage is in these projects -h, --help display help for commandllm-usage context
Usage: llm-usage context [options]
Show peak prompt sizes per model or session, long-context requests and whattheir tier rates added (last 7 days unless --last, --since, --until, or --all)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --all Report every day instead of the last 7 days --last <n> Report the last N days, counting the current day --by-session One row per session instead of per model, largest peak prompt first --top <n> With --by-session, show only the top N sessions (default 20; 0 shows all) --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage blocks
Usage: llm-usage blocks [options]
Show estimated 5-hour usage blocks per source, across machines, with the activeblock (last 7 days unless --last, --since, --until, or --all; only meaningfulfor subscription plans)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --top <n> Show only the top N blocks across sources by cost, or by tokens when a cost is incomplete or with --no-cost (positive integer) --last <n> Report the last N days, counting today (default 7) --all Report every block instead of the last 7 days --compact Abbreviate token counts and leave out minor columns (terminal/markdown) --no-cost Leave cost out of the table, e.g. for screenshots --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage value
Usage: llm-usage value [options]
Compare the API-priced cost of each month with subscription plan prices, perplan and project (full history unless --last, --since, or --until)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --plan <id> Plan to compare with, over the sources it covers (repeatable; default claude-max-20x, or chatgpt-pro-200 when the source filter leaves out claude). Two plans that cover the same source each count its full cost (choices: "claude-pro", "claude-max-5x", "claude-max-20x", "chatgpt-go", "chatgpt-plus", "chatgpt-pro-100", "chatgpt-pro-200", "chatgpt-pro-500") --plan-price <usd> Monthly plan price in USD to use instead of the plan's list price (one plan only) --top <n> List only the top N projects of each month by cost (default 10; 0 lists all) --last <n> Report the last N months, counting the current month --all Report every month since the first usage (the default without date flags) --compact Abbreviate token counts and leave out minor columns (terminal/markdown) --no-cost Leave cost out of the table, e.g. for screenshots --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage wrapped
Usage: llm-usage wrapped [options]
Show a yearly usage recap with an optional share report
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --markdown Render output as markdown table --share Write an interactive HTML report to the current directory --no-open With --share, write the report without opening it --redact With --share, label projects project-N, machines machine-N and local or path-shaped models model-N --year <YYYY> Year to recap (2020-2100; defaults to current local year) --all No effect: wrapped always recaps one year, chosen with --year -h, --help display help for commandllm-usage events
Usage: llm-usage events [options]
Export usage events as JSONL, CSV, or OTLP traces or metrics
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --since <YYYY-MM-DD> Inclusive start date filter --until <YYYY-MM-DD> Inclusive end date filter --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) --no-sync Use other machines' cached usage without refreshing it over ssh --format <name> Export format: jsonl | csv | otlp-traces | otlp-metrics (default: "jsonl") --otel-include-paths With otlp-traces: add repository paths and path-shaped session ids to spans (left out or hashed by default) --otlp-endpoint <url> With an OTLP format: POST to <url>/v1/traces or /v1/metrics (unless <url> already ends with it) instead of printing; headers from OTEL_EXPORTER_OTLP_HEADERS --last <n> Export the last N days, counting today --all Report the full history (the default without date flags) --repo <project> Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after --model picks exact or substring matching -h, --help display help for commandllm-usage pricing <model…>
Usage: llm-usage pricing [options] <model...>
Explain how model names resolve to prices: the matched pricing key and rule,overrides, where the prices came from, rates per 1M tokens and tiers (neverreads usage)
Arguments: model Model names, as they appear in usage logs
Options: --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache --markdown Render output as markdown table --help-all Display help for command -h, --help display help for commandllm-usage statusline
Usage: llm-usage statusline [options]
Print one line with today's cost, your streak, and month to date, led by thesession's cost and context use under Claude Code (for status bars; neverfetches)
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --timezone <iana> Timezone for bucketing (default: system timezone) --provider <name> Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) --model <name> Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --ignore-pricing-failures Continue without estimated costs when pricing cannot be loaded --cost-mode <mode> Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: "explicit", "estimated", "both") --history Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) --no-history Leave out usage from files that no longer exist on disk --machine <name> Count only these machines (repeatable or comma-separated; local is this one; default: all) -h, --help display help for commandllm-usage doctor
Usage: llm-usage doctor [options]
Show where each source is searched, whether its usage is readable, and ledgerhealth
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) -h, --help display help for commandllm-usage prune
Usage: llm-usage prune [options]
Preview or delete departed files from the local event store
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --suppressed Select departed files that --history already suppresses --departed-before <YYYY-MM-DD> Select departed files whose newest event timestamp is strictly before this UTC date --apply Delete selected departed files and vacuum the event store -h, --help display help for commandllm-usage config <init|show|path>
Usage: llm-usage config [options] [command]
Manage user configuration
Options: --help-all Display help for command -h, --help display help for command
Commands: init [options] Write a commented config template show [options] Print the effective configuration and where each value comes from path [options] Print the resolved config file path help [command] display help for command
Usage: llm-usage config init [options]
Write a commented config template
Options: --force Overwrite an existing config file --help-all Display help for command -h, --help display help for command
Usage: llm-usage config show [options]
Print the effective configuration and where each value comes from
Options: --pi-dir <path> Path to .pi sessions directory (repeatable) --codex-dir <path> Path to .codex sessions directory (repeatable) --copilot-dir <path> Path to GitHub Copilot OTEL directory (repeatable) --gemini-dir <path> Path to .gemini directory (repeatable) --droid-dir <path> Path to Droid sessions directory (repeatable) --claude-dir <path> Path to Claude projects directory (repeatable) --openclaw-dir <path> Path to OpenClaw agents directory (repeatable) --opencode-db <path> Path to OpenCode SQLite DB --goose-db <path> Path to Goose SQLite DB --amp-dir <path> Path to Amp threads directory (repeatable) --qwen-dir <path> Path to Qwen projects directory (repeatable) --kimi-dir <path> Path to Kimi sessions directory (repeatable) --cline-dir <path> Path to Cline tasks directory (repeatable) --roocode-dir <path> Path to RooCode tasks directory (repeatable) --kilocode-dir <path> Path to KiloCode tasks directory (repeatable) --antigravity-dir <path> Path to Antigravity conversations directory (repeatable) --dsh-dir <path> Path to DeepSeek Harness sessions directory (repeatable) --help-all Display help including the per-source path flags --source-dir <source-id=path> Override source directory for directory-backed sources (repeatable) --source <name> Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) --json Render output as JSON --timezone <iana> Timezone for bucketing (default: system timezone) --pricing-url <url> Override LiteLLM pricing source URL --pricing-overrides <path> Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) --pricing-offline Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache -h, --help display help for command
Usage: llm-usage config path [options]
Print the resolved config file path
Options: --help-all Display help for command -h, --help display help for commandllm-usage machine <add|list|remove|export>
Usage: llm-usage machine [options] [command]
Combine usage from your other machines over ssh
Options: --help-all Display help for command -h, --help display help for command
Commands: add [options] <name> [ssh-target] Sync a machine over ssh and add it to config.toml; it needs llm-usage-metrics installed and ssh login without a prompt list [options] Show each machine, when it last synced, and how much usage is cached remove [options] <name> Remove a machine from config.toml and delete its cached usage export [options] Print the usage this machine's reports count, as a versioned NDJSON bundle that sync reads help [command] display help for command
Usage: llm-usage machine add [options] <name> [ssh-target]
Sync a machine over ssh and add it to config.toml; it needs llm-usage-metricsinstalled and ssh login without a prompt
Arguments: name Name for the machine in reports (lowercase letters, digits, dashes) ssh-target ssh destination: host, user@host, or an ssh_config alias (default: the name)
Options: --command <command> How llm-usage-metrics is launched there (default: llm-usage) --help-all Display help for command -h, --help display help for command
Usage: llm-usage machine list [options]
Show each machine, when it last synced, and how much usage is cached
Options: --help-all Display help for command -h, --help display help for command
Usage: llm-usage machine remove [options] <name>
Remove a machine from config.toml and delete its cached usage
Arguments: name Machine name
Options: --help-all Display help for command -h, --help display help for command
Usage: llm-usage machine export [options]
Print the usage this machine's reports count, as a versioned NDJSON bundle thatsync reads
Options: --known <path> Leave out files already held at the same revision, as listed in this JSON file (- for stdin) --quiet Suppress informational stderr output (warnings still print) --verbose Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) --help-all Display help for command -h, --help display help for commandllm-usage sync
Usage: llm-usage sync [options] [names...]
Fetch your other machines' usage now (reports also fetch it when it is 10minutes old)
Arguments: names Machines to sync (default: every enabled machine)
Options: --full Fetch every file again instead of only the changed ones --help-all Display help for command -h, --help display help for commandllm-usage schema
Usage: llm-usage schema [options] [name]
Print a bundled report JSON Schema
Arguments: name Schema name: blocks, compare, config, config-show, context, doctor, efficiency, events-line, machine-export, optimize, pricing, projects, prune, session, share, summary, tools, trends, usage, value, wrapped
Options: --list List available schema names (the default without a name) --help-all Display help for command -h, --help display help for commandllm-usage completion
Usage: llm-usage completion [options] <shell>
Print a shell completion script (bash, zsh, or fish)
Arguments: shell Shell: bash | zsh | fish
Options: --help-all Display help for command -h, --help display help for commandOption index
Section titled “Option index”Search across root and command help. See Command help above to check which flags a command accepts.
| Option | Short | Argument | Description |
|---|---|---|---|
--all |
- | - | summary: No effect: the summary always covers today, the last 7 days and month to date; hourly: Report every hour instead of today; daily, context: Report every day instead of the last 7 days; weekly: Report every week instead of the last 8 weeks; monthly, projects, efficiency, optimize, session, events: Report the full history (the default without date flags); compare: No effect: compare reads its two windows from the date flags; trends: Chart every day since the first usage instead of the last 30 days; tools: Report every tool call on disk instead of the last 7 days; blocks: Report every block instead of the last 7 days; value: Report every month since the first usage (the default without date flags); wrapped: No effect: wrapped always recaps one year, chosen with –year |
--amp-dir |
- | <path> |
Path to Amp threads directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--antigravity-dir |
- | <path> |
Path to Antigravity conversations directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--apply |
- | - | Delete selected departed files and vacuum the event store (prune only) |
--by-machine |
- | - | Split each source row by the machine its usage came from (usage reports only) |
--by-repo |
- | - | hourly, daily, weekly, monthly: Split each source row by project (the working directory the tool recorded); compare: Also compare each project (the working directory the tool recorded); trends: Render one sparkline row per project (the working directory the tool recorded); not with –by-source; session: Group usage by project (the working directory the tool recorded) instead of by session; tools: Split each tool row by project (the working directory the tool recorded) |
--by-session |
- | - | One row per session instead of per model, largest peak prompt first (context 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; tools: Split each tool row by source |
--candidate-model |
- | <name> |
Candidate model for counterfactual pricing (repeatable or comma-separated) (optimize only) |
--claude-dir |
- | <path> |
Path to Claude projects directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--cline-dir |
- | <path> |
Path to Cline tasks directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--codex-dir |
- | <path> |
Path to .codex sessions directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--command |
- | <command> |
How llm-usage-metrics is launched there (default: llm-usage) (machine only) |
--compact |
- | - | hourly, daily, weekly, monthly: Abbreviate token counts and hide the Reasoning and Cache Write columns (terminal/Markdown); projects, blocks, value: Abbreviate token counts and leave out minor columns (terminal/Markdown) |
--copilot-dir |
- | <path> |
Path to GitHub Copilot OTEL directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--cost-mode |
- | <mode> |
Costs to report: explicit (logged by the source), estimated (from LiteLLM), or both (logged, else estimated; default) (choices: “explicit”, “estimated”, “both”) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, context, blocks, value, wrapped, events, statusline only) |
--days |
- | <n> |
Alias of –last (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 (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--dsh-dir |
- | <path> |
Path to DeepSeek Harness sessions directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--force |
- | - | Overwrite an existing config file (config only) |
--format |
- | <name> |
Export format: jsonl | csv | otlp-traces | otlp-metrics (default: “jsonl”) (events only) |
--full |
- | - | Fetch every file again instead of only the changed ones (sync only) |
--gemini-dir |
- | <path> |
Path to .gemini directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--goose-db |
- | <path> |
Path to Goose SQLite DB (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--granularity |
- | <period> |
Add rows per period and project (choices: “daily”, “weekly”, “monthly”) (projects only) |
--help-all |
- | - | summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune: Display help including the per-source path flags; pricing, config, machine, sync, schema, completion: Display help for command |
--history |
- | - | Include usage from files that no longer exist on disk (on by default; when passed, fails if the event store is unavailable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline 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 (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, context, blocks, value, wrapped, events, statusline only) |
--include-merge-commits |
- | - | Include merge commits in Git outcome metrics (efficiency only) |
--json |
- | - | Render output as JSON (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, pricing, doctor, prune, config only) |
--kilocode-dir |
- | <path> |
Path to KiloCode tasks directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--kimi-dir |
- | <path> |
Path to Kimi sessions directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--known |
- | <path> |
Leave out files already held at the same revision, as listed in this JSON file (- for stdin) (machine only) |
--last |
- | <n> |
hourly: Report the last N days hour by hour (1-31), counting today; daily, context: Report the last N days, counting the current day; weekly: Report the last N weeks, counting the current week; monthly, projects, value: Report the last N months, counting the current month; trends: Chart the last N local calendar days, counting today; defaults to 30 when no date flags are provided; tools, blocks: Report the last N days, counting today (default 7); events: Export the last N days, counting today |
--list |
- | - | List available schema names (the default without a name) (schema only) |
--machine |
- | <name> |
Count only these machines (repeatable or comma-separated; local is this one; default: all) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline only) |
--markdown |
- | - | Render output as Markdown table (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, pricing only) |
--metric |
- | <name> |
Trend metric: cost | tokens | active-hours (default: “cost”) (trends only) |
--model |
- | <name> |
Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, context, blocks, value, wrapped, events, statusline only) |
--no-cost |
- | - | hourly, projects, blocks, value: Leave cost out of the table, e.g. for screenshots; daily, weekly, monthly: Leave cost out of the table and share report, e.g. for screenshots |
--no-history |
- | - | Leave out usage from files that no longer exist on disk (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline only) |
--no-open |
- | - | With –share, write the report without opening it (summary, daily, weekly, monthly, compare, efficiency, optimize, trends, wrapped only) |
--no-sync |
- | - | Use other machines’ cached usage without refreshing it over ssh (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events only) |
--openclaw-dir |
- | <path> |
Path to OpenClaw agents directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--opencode-db |
- | <path> |
Path to OpenCode SQLite DB (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--otel-include-paths |
- | - | With otlp-traces: add repository paths and path-shaped session ids to spans (left out or hashed by default) (events only) |
--otlp-endpoint |
- | <url> |
With an OTLP format: POST to <url>/v1/traces or /v1/metrics (unless <url> already ends with it) instead of printing; headers from OTEL_EXPORTER_OTLP_HEADERS (events only) |
--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 (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--plan |
- | <id> |
Plan to compare with, over the sources it covers (repeatable; default claude-max-20x, or chatgpt-pro-200 when the source filter leaves out claude). Two plans that cover the same source each count its full cost (choices: “claude-pro”, “claude-max-5x”, “claude-max-20x”, “chatgpt-go”, “chatgpt-plus”, “chatgpt-pro-100”, “chatgpt-pro-200”, “chatgpt-pro-500”) (value only) |
--plan-price |
- | <usd> |
Monthly plan price in USD to use instead of the plan’s list price (one plan only) (value only) |
--pricing-offline |
- | - | Never fetch pricing: use the cached LiteLLM pricing, or the bundled snapshot when there is no cache (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, context, blocks, value, wrapped, events, pricing, config only) |
--pricing-overrides |
- | <path> |
Path to a JSON file of per-model pricing overrides (takes precedence over LiteLLM) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, context, blocks, value, wrapped, events, pricing, statusline, config only) |
--pricing-url |
- | <url> |
Override LiteLLM pricing source URL (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, context, blocks, value, wrapped, events, pricing, config only) |
--provider |
- | <name> |
Billing-provider filter (normalized to billing entity; e.g. openai, anthropic, google, moonshot) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, context, blocks, value, wrapped, events, statusline only) |
--quiet |
- | - | Suppress informational stderr output (warnings still print) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, pricing, doctor, prune, machine only) |
--qwen-dir |
- | <path> |
Path to Qwen projects directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--redact |
- | - | With –share, label projects project-N, machines machine-N and local or path-shaped models model-N (summary, daily, weekly, monthly, compare, efficiency, optimize, trends, wrapped only) |
--repo |
- | <project> |
summary, hourly, daily, weekly, monthly, projects, compare, optimize, trends, session, context, blocks, value, events: Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after –model picks exact or substring matching; efficiency: Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Applied after –model picks exact or substring matching. It filters usage events; –repo-dir picks the Git repository for outcomes; tools: Count only these projects (repeatable or comma-separated, so a value cannot contain a comma). A path (absolute, or ./, ../, ~/ on this machine) matches that project directory and the projects under it; a name or path tail such as work/api matches the end of a project directory, not the projects under it; (unattributed) matches usage without a recorded directory. Keeps the tool calls of sessions whose usage is in these projects |
--repo-dir |
- | <path> |
Path to repository for Git outcome metrics (efficiency only) |
--roocode-dir |
- | <path> |
Path to RooCode tasks directory (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--share |
- | - | Write an interactive HTML report to the current directory (summary, daily, weekly, monthly, compare, efficiency, optimize, trends, wrapped only) |
--since |
- | <YYYY-MM-DD> |
Inclusive start date filter (hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, events only) |
--source |
- | <name> |
Filter by source id (repeatable or comma-separated, supported sources (17): pi, codex, gemini, droid, opencode, openclaw, claude, copilot, goose, amp, qwen, kimi, cline, roocode, kilocode, antigravity, dsh) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--source-dir |
- | <source-id=path> |
Override source directory for directory-backed sources (repeatable) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, config only) |
--suppressed |
- | - | Select departed files that –history already suppresses (prune only) |
--timeline |
- | - | With –id naming one session: list its requests in time order with a running cost, between its tool calls and turns (session only) |
--timezone |
- | <iana> |
Timezone for bucketing (default: system timezone) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, config only) |
--top |
- | <n> |
projects: Show only the top N projects by cost (default 10; 0 shows all); optimize: Show only the top N cheapest candidates (positive integer); session: Show only the top N rows by cost (default 20; 0 shows all); tools: Show only the top N tools by calls (default 20; 0 shows all); context: With –by-session, show only the top N sessions (default 20; 0 shows all); blocks: Show only the top N blocks across sources by cost, or by tokens when a cost is incomplete or with –no-cost (positive integer); value: List only the top N projects of each month by cost (default 10; 0 lists all) |
--until |
- | <YYYY-MM-DD> |
Inclusive end date filter (hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, events only) |
--verbose |
- | - | Print detailed diagnostics on stderr (per-source counts, routine skips, config, env) (summary, hourly, daily, weekly, monthly, projects, compare, efficiency, optimize, trends, session, tools, context, blocks, value, wrapped, events, statusline, doctor, prune, machine 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-usagellm-usage summary --jsonllm-usage hourlyllm-usage hourly --last 3 --jsonllm-usage hourly --since 2026-06-15 --until 2026-06-15 --by-repollm-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 daily --compactllm-usage weekly --timezone Europe/Parisllm-usage weekly --all --jsonllm-usage weekly --last 1 --no-costllm-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 --no-history --pricing-offlinellm-usage monthly --source droid --droid-dir /path/to/.factory/sessionsllm-usage monthly --sharellm-usage monthly --last 3llm-usage projectsllm-usage projects --last 3 --top 0llm-usage projects --granularity monthly --jsonllm-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 --last 7llm-usage trends --by-source --jsonllm-usage sessionllm-usage session --top 5 --jsonllm-usage session --id 486cllm-usage session --id 486c --timelinellm-usage session --by-repo --top 5llm-usage session --markdownllm-usage toolsllm-usage tools --by-source --top 10llm-usage tools --last 30 --jsonllm-usage tools --by-repo --markdownllm-usage contextllm-usage context --by-session --top 5llm-usage context --last 30 --jsonllm-usage context --source claude --markdownllm-usage blocksllm-usage blocks --source claude --last 1llm-usage blocks --all --top 5 --jsonllm-usage valuellm-usage value --plan claude-max-5x --plan chatgpt-plusllm-usage value --plan claude-pro --plan-price 18 --last 6 --jsonllm-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 events --format otlp-traces --since 2026-06-01 > traces.jsonlllm-usage events --format otlp-metrics --since 2026-06-01 > metrics.jsonlllm-usage events --format otlp-traces --otlp-endpoint http://127.0.0.1:4318llm-usage pricing claude-sonnet-4-5llm-usage pricing gpt-5 gpt-5-codex --jsonllm-usage pricing my-model --pricing-overrides ./overrides.jsonllm-usage statuslinellm-usage statusline --source claudellm-usage doctorllm-usage doctor --jsonllm-usage prune --suppressedllm-usage prune --departed-before 2026-01-01 --apply