Skip to content
LLM Usage Metrics

Optimize

optimize replays your observed token mix against one or more candidate model prices.

llm-usage optimize <daily|weekly|monthly> --candidate-model <model> [options]

Examples

Section titled “Examples”
Terminal window
# Compare two OpenAI candidates for monthly usage
llm-usage optimize monthly \
  --provider openai \
  --candidate-model gpt-4.1 \
  --candidate-model gpt-5-codex


# Keep only the cheapest candidate in output
llm-usage optimize weekly \
  --provider openai \
  --candidate-model gpt-4.1,gpt-5-codex \
  --top 1 \
  --json


# Write an interactive HTML report
llm-usage optimize monthly \
  --provider openai \
  --candidate-model gpt-4.1 \
  --candidate-model gpt-5-codex \
  --share

Command behavior

Section titled “Command behavior”
  • Uses the same source discovery and filtering pipeline as usage reports.
  • Requires at least one --candidate-model.
  • Enforces a single provider context after filtering.
  • If multiple providers remain, narrow with --provider.
  • --provider matches canonical billing entities after provider normalization.
  • Provider aliases are normalized to billing roots first (for example, openai-codex is treated as openai).
  • Candidate ranking is deterministic and based on ALL period hypothetical cost; --top N keeps the N cheapest candidates.
  • Without date flags, the report covers your full history. The shared filters apply, including --repo to price only some projects.

Missing pricing and incomplete baselines

Section titled “Missing pricing and incomplete baselines”
  • Missing candidate pricing on non-zero token periods marks candidate cost as incomplete.
  • A candidate without a published cache-write rate bills cache creation as regular input (as OpenAI-style automatic caching does), so baseline cache writes are priced at its input rate and the row carries the cache_write_priced_as_input note.
  • If baseline cost is incomplete, savings fields are omitted.
  • If all billable token buckets are zero but baseline has cost, savings are omitted and a warning is emitted to stderr.

Output formats

Section titled “Output formats”
  • --json emits optimize rows under data in the versioned report envelope.
  • --markdown emits a Markdown table.
  • Default terminal output renders a titled table.
  • --share writes an interactive report optimize-<granularity>-share.html, with the candidate comparison as a panel, to the current working directory.
  • Diagnostics and warnings always go to stderr.