llm-usage-metrics 0.3.6 → 0.3.7

package/dist/index.js

@@ -538,7 +538,15 @@ function isTruthyEnvFlag(value) {
 }
 function shouldSkipUpdateCheckForArgv(argv) {
   const executableArgs = argv.slice(2);
-  const commandNames = /* @__PURE__ */ new Set(["daily", "weekly", "monthly", "efficiency", "help", "version"]);
+  const commandNames = /* @__PURE__ */ new Set([
+    "daily",
+    "weekly",
+    "monthly",
+    "efficiency",
+    "optimize",
+    "help",
+    "version"
+  ]);
   if (executableArgs.length === 0) {
     return false;
   }
@@ -674,6 +682,35 @@ function normalizeModelList(models) {
   return [...deduplicated].sort(compareByCodePoint);
 }
 
+// src/domain/provider-normalization.ts
+var billingProviderAliases = /* @__PURE__ */ new Map([
+  ["openai-codex", "openai"],
+  ["github-copilot", "github"]
+]);
+var billingProviderPrefixAliases = [
+  ["openai-", "openai"],
+  ["openai/", "openai"]
+];
+function normalizeProviderToBillingEntity(provider) {
+  if (!provider) {
+    return void 0;
+  }
+  const normalizedProvider = provider.trim().toLowerCase();
+  if (normalizedProvider.length === 0) {
+    return void 0;
+  }
+  const aliasedProvider = billingProviderAliases.get(normalizedProvider);
+  if (aliasedProvider) {
+    return aliasedProvider;
+  }
+  for (const [prefix, billingProvider] of billingProviderPrefixAliases) {
+    if (normalizedProvider.startsWith(prefix)) {
+      return billingProvider;
+    }
+  }
+  return normalizedProvider;
+}
+
 // src/domain/usage-event.ts
 function normalizeSourceId(value) {
   if (typeof value !== "string") {
@@ -696,6 +733,9 @@ function normalizeOptionalText(value) {
   const normalized = value.trim();
   return normalized || void 0;
 }
+function normalizeOptionalProvider(value) {
+  return normalizeProviderToBillingEntity(value);
+}
 function normalizeOptionalPath(value) {
   return normalizeOptionalText(value);
 }
@@ -735,7 +775,7 @@ function createUsageEvent(input) {
     sessionId: requireText(input.sessionId, "sessionId"),
     timestamp: normalizeTimestamp(input.timestamp),
     repoRoot: normalizeOptionalPath(input.repoRoot),
-    provider: normalizeOptionalText(input.provider),
+    provider: normalizeOptionalProvider(input.provider),
     model: normalizeOptionalModel(input.model),
     inputTokens,
     outputTokens,
@@ -3264,6 +3304,42 @@ async function attributeUsageEventsToRepo(events, repoDir, resolveRepoRoot3 = re
   };
 }
 
+// src/cli/build-usage-data-diagnostics.ts
+function buildUsageDiagnostics(params) {
+  const parseResultBySource = new Map(
+    params.successfulParseResults.map((result) => [result.source.toLowerCase(), result])
+  );
+  const sessionStats = params.adaptersToParse.map((adapter) => {
+    const parseResult = parseResultBySource.get(adapter.id.toLowerCase());
+    return {
+      source: adapter.id,
+      filesFound: parseResult?.filesFound ?? 0,
+      eventsParsed: parseResult?.events.length ?? 0
+    };
+  });
+  const skippedRows = params.successfulParseResults.filter((result) => result.skippedRows > 0).map((result) => ({
+    source: result.source,
+    skippedRows: result.skippedRows,
+    reasons: result.skippedRowReasons
+  }));
+  return {
+    sessionStats,
+    sourceFailures: params.sourceFailures,
+    skippedRows,
+    pricingOrigin: params.pricingOrigin,
+    pricingWarning: params.pricingWarning,
+    activeEnvOverrides: params.activeEnvOverrides,
+    timezone: params.timezone
+  };
+}
+function assembleUsageDataResult(events, rows, diagnostics) {
+  return {
+    events,
+    rows,
+    diagnostics
+  };
+}
+
 // src/config/env-var-display.ts
 var ENV_VARS_TO_DISPLAY = [
   { name: "LLM_USAGE_SKIP_UPDATE_CHECK", description: "skip startup update check" },
@@ -3304,42 +3380,6 @@ function formatEnvVarOverrides(overrides) {
   return lines;
 }
 
-// src/cli/build-usage-data-diagnostics.ts
-function buildUsageDiagnostics(params) {
-  const parseResultBySource = new Map(
-    params.successfulParseResults.map((result) => [result.source.toLowerCase(), result])
-  );
-  const sessionStats = params.adaptersToParse.map((adapter) => {
-    const parseResult = parseResultBySource.get(adapter.id.toLowerCase());
-    return {
-      source: adapter.id,
-      filesFound: parseResult?.filesFound ?? 0,
-      eventsParsed: parseResult?.events.length ?? 0
-    };
-  });
-  const skippedRows = params.successfulParseResults.filter((result) => result.skippedRows > 0).map((result) => ({
-    source: result.source,
-    skippedRows: result.skippedRows,
-    reasons: result.skippedRowReasons
-  }));
-  return {
-    sessionStats,
-    sourceFailures: params.sourceFailures,
-    skippedRows,
-    pricingOrigin: params.pricingOrigin,
-    pricingWarning: params.pricingWarning,
-    activeEnvOverrides: params.activeEnvOverrides,
-    timezone: params.timezone
-  };
-}
-function assembleUsageDataResult(events, rows, diagnostics) {
-  return {
-    events,
-    rows,
-    diagnostics
-  };
-}
-
 // src/cli/build-usage-data-inputs.ts
 function validateDateInput(value, flagName) {
   if (!/^\d{4}-\d{2}-\d{2}$/u.test(value)) {
@@ -3359,11 +3399,7 @@ function validateTimezone(timezone) {
   }
 }
 function normalizeProviderFilter(provider) {
-  if (!provider) {
-    return void 0;
-  }
-  const normalized = provider.trim().toLowerCase();
-  return normalized || void 0;
+  return normalizeProviderToBillingEntity(provider);
 }
 function normalizeSourceFilter(source) {
   if (!source || Array.isArray(source) && source.length === 0) {
@@ -3540,7 +3576,7 @@ function normalizeSkippedRowReasons(value) {
 // src/cli/parse-file-cache.ts
 import { mkdir as mkdir2, readFile as readFile4, rename, rm, stat as stat3, writeFile as writeFile2 } from "fs/promises";
 import path11 from "path";
-var PARSE_FILE_CACHE_VERSION = 2;
+var PARSE_FILE_CACHE_VERSION = 3;
 var CACHE_KEY_SEPARATOR = "\0";
 function createCacheKey(source, filePath) {
   return `${source}${CACHE_KEY_SEPARATOR}${filePath}`;
@@ -3599,7 +3635,9 @@ function normalizeCachedUsageEvent(value) {
   if (inputTokens === void 0 || outputTokens === void 0 || reasoningTokens === void 0 || cacheReadTokens === void 0 || cacheWriteTokens === void 0 || totalTokens === void 0) {
     return void 0;
   }
-  const provider = typeof record.provider === "string" ? record.provider.trim() : "";
+  const provider = normalizeProviderToBillingEntity(
+    typeof record.provider === "string" ? record.provider : void 0
+  );
   const model = typeof record.model === "string" ? record.model.trim().toLowerCase() : "";
   const costUsd = toNonNegativeNumber2(record.costUsd);
   if (costMode === "explicit" && costUsd === void 0) {
@@ -3610,7 +3648,7 @@ function normalizeCachedUsageEvent(value) {
     sessionId,
     timestamp,
     repoRoot: repoRoot || void 0,
-    provider: provider || void 0,
+    provider,
     model: model || void 0,
     inputTokens,
     outputTokens,
@@ -4745,9 +4783,20 @@ function shouldLoadPricingSource(events) {
   }
   return events.some((event) => eventNeedsPricingLookup(event));
 }
-async function resolveAndApplyPricingToEvents(events, options, runtimeConfig = getPricingFetcherRuntimeConfig(), loadPricingSource = resolvePricingSource) {
+function hasAnyBillableTokenBuckets(events) {
+  return events.some(
+    (event) => event.inputTokens > 0 || event.outputTokens > 0 || event.reasoningTokens > 0 || event.cacheReadTokens > 0 || event.cacheWriteTokens > 0
+  );
+}
+function shouldLoadPricingSourceForMode(events, pricingLoadMode) {
+  if (pricingLoadMode === "force") {
+    return hasAnyBillableTokenBuckets(events);
+  }
+  return shouldLoadPricingSource(events);
+}
+async function resolveAndApplyPricingToEvents(events, options, runtimeConfig = getPricingFetcherRuntimeConfig(), loadPricingSource = resolvePricingSource, pricingLoadMode = "auto") {
   let pricingOrigin = "none";
-  if (!shouldLoadPricingSource(events)) {
+  if (!shouldLoadPricingSourceForMode(events, pricingLoadMode)) {
     return {
       pricedEvents: events,
       pricingOrigin
@@ -4771,11 +4820,12 @@ async function resolveAndApplyPricingToEvents(events, options, runtimeConfig = g
   pricingOrigin = pricingResult.origin;
   return {
     pricedEvents: applyPricingToEvents(events, pricingResult.source),
-    pricingOrigin
+    pricingOrigin,
+    pricingSource: pricingResult.source
   };
 }
 
-// src/cli/build-usage-data.ts
+// src/cli/build-usage-event-dataset.ts
 function withNormalizedPricingUrl(options, normalizedPricingUrl) {
   if (options.pricingUrl === normalizedPricingUrl) {
     return options;
@@ -4785,13 +4835,11 @@ function withNormalizedPricingUrl(options, normalizedPricingUrl) {
     pricingUrl: normalizedPricingUrl
   };
 }
-async function buildUsageData(granularity, options, deps = {}) {
+async function buildUsageEventDataset(options, deps = {}) {
   const normalizedInputs = normalizeBuildUsageInputs(options);
   const readParsingRuntimeConfig = deps.getParsingRuntimeConfig ?? getParsingRuntimeConfig;
   const readPricingRuntimeConfig = deps.getPricingFetcherRuntimeConfig ?? getPricingFetcherRuntimeConfig;
   const makeAdapters = deps.createAdapters ?? createDefaultAdapters;
-  const loadPricingSource = deps.resolvePricingSource ?? resolvePricingSource;
-  const readEnvVarOverrides = deps.getActiveEnvVarOverrides ?? getActiveEnvVarOverrides;
   const parsingRuntimeConfig = readParsingRuntimeConfig();
   const pricingRuntimeConfig = readPricingRuntimeConfig();
   const adapters = makeAdapters(options);
@@ -4816,26 +4864,53 @@ async function buildUsageData(granularity, options, deps = {}) {
     providerFilter: normalizedInputs.providerFilter,
     modelFilter: normalizedInputs.modelFilter
   });
-  const pricingOptions = withNormalizedPricingUrl(options, normalizedInputs.pricingUrl);
-  const { pricedEvents, pricingOrigin, pricingWarning } = await resolveAndApplyPricingToEvents(
+  return {
+    options,
+    normalizedInputs,
+    adaptersToParse,
+    successfulParseResults,
+    sourceFailures,
     filteredEvents,
-    pricingOptions,
     pricingRuntimeConfig,
-    loadPricingSource
+    readEnvVarOverrides: deps.getActiveEnvVarOverrides ?? getActiveEnvVarOverrides
+  };
+}
+async function applyPricingToUsageEventDataset(dataset, deps = {}, pricingLoadMode = "auto") {
+  const loadPricingSource = deps.resolvePricingSource ?? resolvePricingSource;
+  const pricingOptions = withNormalizedPricingUrl(
+    dataset.options,
+    dataset.normalizedInputs.pricingUrl
+  );
+  return resolveAndApplyPricingToEvents(
+    dataset.filteredEvents,
+    pricingOptions,
+    dataset.pricingRuntimeConfig,
+    loadPricingSource,
+    pricingLoadMode
+  );
+}
+
+// src/cli/build-usage-data.ts
+async function buildUsageData(granularity, options, deps = {}) {
+  const dataset = await buildUsageEventDataset(options, deps);
+  const { pricedEvents, pricingOrigin, pricingWarning } = await applyPricingToUsageEventDataset(
+    dataset,
+    deps,
+    "auto"
   );
   const rows = aggregateUsage(pricedEvents, {
     granularity,
-    timezone: normalizedInputs.timezone,
-    sourceOrder: adaptersToParse.map((adapter) => adapter.id)
+    timezone: dataset.normalizedInputs.timezone,
+    sourceOrder: dataset.adaptersToParse.map((adapter) => adapter.id)
   });
   const diagnostics = buildUsageDiagnostics({
-    adaptersToParse,
-    successfulParseResults,
-    sourceFailures,
+    adaptersToParse: dataset.adaptersToParse,
+    successfulParseResults: dataset.successfulParseResults,
+    sourceFailures: dataset.sourceFailures,
     pricingOrigin,
     pricingWarning,
-    activeEnvOverrides: readEnvVarOverrides(),
-    timezone: normalizedInputs.timezone
+    activeEnvOverrides: dataset.readEnvVarOverrides(),
+    timezone: dataset.normalizedInputs.timezone
   });
   return assembleUsageDataResult(pricedEvents, rows, diagnostics);
 }
@@ -5252,6 +5327,7 @@ function warnIfTerminalTableOverflows(reportOutput, warn, stdoutState = process.
 
 // src/render/render-efficiency-report.ts
 import { markdownTable } from "markdown-table";
+import pc5 from "picocolors";
 
 // src/render/report-header.ts
 import pc2 from "picocolors";
@@ -5397,8 +5473,8 @@ function resolveSourceStyler(source, palette = defaultTerminalStylePalette) {
 var rowTypeStylePolicies = {
   period_source: (cells, palette) => {
     const styledCells = [...cells];
-    const costColumnIndex = styledCells.length - 1;
-    styledCells[costColumnIndex] = styleCellLines(styledCells[costColumnIndex], palette.yellow);
+    const costColumnIndex2 = styledCells.length - 1;
+    styledCells[costColumnIndex2] = styleCellLines(styledCells[costColumnIndex2], palette.yellow);
     return styledCells;
   },
   period_combined: (cells, palette) => cells.map((cell, cellIndex) => {
@@ -5843,6 +5919,14 @@ function renderTerminalTable(rows, options = {}) {
 // src/render/render-efficiency-report.ts
 var periodColumnIndex = 0;
 var minimumEfficiencyColumnWidth = 1;
+var commitsColumnIndex = 1;
+var linesAddedColumnIndex = 2;
+var linesDeletedColumnIndex = 3;
+var linesChangedColumnIndex = 4;
+var costColumnIndex = 11;
+var usdPerCommitColumnIndex = 12;
+var usdPer1kLinesChangedColumnIndex = 13;
+var commitsPerUsdColumnIndex = 16;
 function getReportTitle(granularity) {
   switch (granularity) {
     case "daily":
@@ -5981,9 +6065,67 @@ function fitTableCellsToTerminal(headerCells, bodyRows) {
     widths: constrainedWidths
   };
 }
-function renderTerminalEfficiencyTable(rows) {
+function styleDeltaCell(value, formattedValue, options) {
+  if (!options.useColor) {
+    return formattedValue;
+  }
+  if (value > 0) {
+    return pc5.green(formattedValue);
+  }
+  if (value < 0) {
+    return pc5.red(formattedValue);
+  }
+  return pc5.dim(formattedValue);
+}
+function styleEfficiencyTerminalRows(rows, bodyRows, options) {
+  return bodyRows.map((cells, rowIndex) => {
+    if (!options.useColor) {
+      return [...cells];
+    }
+    const row = rows[rowIndex];
+    const styledCells = [...cells];
+    const periodCell = styledCells[periodColumnIndex];
+    styledCells[periodColumnIndex] = row.rowType === "grand_total" ? pc5.bold(pc5.cyan(periodCell)) : pc5.bold(periodCell);
+    styledCells[commitsColumnIndex] = pc5.bold(styledCells[commitsColumnIndex]);
+    styledCells[linesAddedColumnIndex] = styleDeltaCell(
+      row.linesAdded,
+      styledCells[linesAddedColumnIndex],
+      options
+    );
+    styledCells[linesDeletedColumnIndex] = styleDeltaCell(
+      row.linesDeleted * -1,
+      styledCells[linesDeletedColumnIndex],
+      options
+    );
+    styledCells[linesChangedColumnIndex] = styleDeltaCell(
+      row.linesChanged,
+      styledCells[linesChangedColumnIndex],
+      options
+    );
+    const costValue = row.costUsd;
+    if (costValue !== void 0 && costValue > 0) {
+      styledCells[costColumnIndex] = pc5.yellow(styledCells[costColumnIndex]);
+    }
+    const usdPerCommitValue = row.usdPerCommit;
+    if (usdPerCommitValue !== void 0 && usdPerCommitValue > 0) {
+      styledCells[usdPerCommitColumnIndex] = pc5.yellow(styledCells[usdPerCommitColumnIndex]);
+    }
+    const usdPer1kLinesChangedValue = row.usdPer1kLinesChanged;
+    if (usdPer1kLinesChangedValue !== void 0 && usdPer1kLinesChangedValue > 0) {
+      styledCells[usdPer1kLinesChangedColumnIndex] = pc5.yellow(
+        styledCells[usdPer1kLinesChangedColumnIndex]
+      );
+    }
+    const commitsPerUsdValue = row.commitsPerUsd;
+    if (commitsPerUsdValue !== void 0 && commitsPerUsdValue > 0) {
+      styledCells[commitsPerUsdColumnIndex] = pc5.green(styledCells[commitsPerUsdColumnIndex]);
+    }
+    return styledCells;
+  });
+}
+function renderTerminalEfficiencyTable(rows, options) {
   const headerCells = Array.from(efficiencyTableHeaders);
-  const bodyRows = toEfficiencyTableCells(rows);
+  const bodyRows = styleEfficiencyTerminalRows(rows, toEfficiencyTableCells(rows), options);
   const tableSortRows = rows.map((row) => toTableSortRow(row));
   const fittedCells = fitTableCellsToTerminal(headerCells, bodyRows);
   return renderUnicodeTable({
@@ -6020,7 +6162,7 @@ function renderTerminalEfficiencyReport(efficiencyData, options) {
     })
   );
   outputLines.push("");
-  outputLines.push(renderTerminalEfficiencyTable(efficiencyData.rows));
+  outputLines.push(renderTerminalEfficiencyTable(efficiencyData.rows, { useColor }));
   return outputLines.join("\n");
 }
 function renderEfficiencyReport(efficiencyData, format, options) {
@@ -6083,25 +6225,656 @@ async function runEfficiencyReport(granularity, options) {
   console.log(preparedReport.output);
 }
 
-// src/render/markdown-table.ts
+// src/render/render-optimize-report.ts
 import { markdownTable as markdownTable2 } from "markdown-table";
-var alignment = ["l", "l", "l", "r", "r", "r", "r", "r", "r", "r"];
+import pc6 from "picocolors";
+var optimizeTableHeadersWithNotes = [
+  "Period",
+  "Candidate",
+  "Hypothetical Cost",
+  "Baseline Cost",
+  "Savings",
+  "Savings %",
+  "Notes"
+];
+var optimizeTableHeadersWithoutNotes = [
+  "Period",
+  "Candidate",
+  "Hypothetical Cost",
+  "Baseline Cost",
+  "Savings",
+  "Savings %"
+];
+var usdFormatter3 = new Intl.NumberFormat("en-US", {
+  style: "currency",
+  currency: "USD",
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2
+});
+function getReportTitle2(granularity) {
+  switch (granularity) {
+    case "daily":
+      return "Daily Optimize Report";
+    case "weekly":
+      return "Weekly Optimize Report";
+    case "monthly":
+      return "Monthly Optimize Report";
+  }
+}
+function formatUsd3(value, options = {}) {
+  if (value === void 0) {
+    return "-";
+  }
+  const formatted = usdFormatter3.format(value);
+  return options.approximate ? `~${formatted}` : formatted;
+}
+function formatPercent(value) {
+  if (value === void 0) {
+    return "-";
+  }
+  return `${(value * 100).toFixed(2)}%`;
+}
+function formatNotes(notes) {
+  if (!notes || notes.length === 0) {
+    return "-";
+  }
+  return notes.join(", ");
+}
+function styleCandidateCell(candidateValue, rowType, useColor) {
+  if (!useColor) {
+    return candidateValue;
+  }
+  if (rowType === "baseline") {
+    return pc6.bold(pc6.cyan(candidateValue));
+  }
+  return pc6.bold(candidateValue);
+}
+function styleDeltaCell2(value, formattedValue, useColor) {
+  if (!useColor || value === void 0) {
+    return formattedValue;
+  }
+  if (value > 0) {
+    return pc6.green(formattedValue);
+  }
+  if (value < 0) {
+    return pc6.red(formattedValue);
+  }
+  return pc6.dim(formattedValue);
+}
+function styleNotesCell(notes, formattedNotes, useColor) {
+  if (!useColor || !notes || notes.length === 0) {
+    return formattedNotes;
+  }
+  return pc6.yellow(formattedNotes);
+}
+function formatAbsoluteUsd(value) {
+  return usdFormatter3.format(Math.abs(value));
+}
+function resolveTerminalContextLines(optimizeData, options) {
+  const allBaselineRow = optimizeData.rows.find(
+    (row) => row.rowType === "baseline" && row.periodKey === "ALL"
+  );
+  const allCandidateRows = optimizeData.rows.filter(
+    (row) => row.rowType === "candidate" && row.periodKey === "ALL"
+  );
+  const lines = [];
+  const providerLine = `Provider scope: ${optimizeData.diagnostics.provider}`;
+  lines.push(options.useColor ? pc6.cyan(providerLine) : providerLine);
+  if (allBaselineRow) {
+    lines.push(
+      `ALL baseline cost: ${formatUsd3(allBaselineRow.baselineCostUsd, { approximate: allBaselineRow.baselineCostIncomplete })}`
+    );
+  }
+  if (allCandidateRows.length > 0) {
+    const rowsWithSavings = allCandidateRows.filter((row) => row.savingsUsd !== void 0);
+    const bestRow = rowsWithSavings.length > 0 ? rowsWithSavings.reduce(
+      (best, current) => (current.savingsUsd ?? Number.NEGATIVE_INFINITY) > (best.savingsUsd ?? Number.NEGATIVE_INFINITY) ? current : best
+    ) : void 0;
+    if (!bestRow || bestRow.savingsUsd === void 0) {
+      lines.push("ALL best candidate: unavailable (missing baseline or candidate pricing)");
+    } else if (bestRow.savingsUsd > 0) {
+      lines.push(
+        `ALL best candidate: ${bestRow.candidateModel} saves ${formatAbsoluteUsd(bestRow.savingsUsd)} (${formatPercent(bestRow.savingsPct)})`
+      );
+    } else if (bestRow.savingsUsd < 0) {
+      lines.push(
+        `ALL best candidate: ${bestRow.candidateModel} increases cost by ${formatAbsoluteUsd(bestRow.savingsUsd)} (${formatPercent(bestRow.savingsPct)})`
+      );
+    } else {
+      lines.push(`ALL best candidate: ${bestRow.candidateModel} matches baseline cost`);
+    }
+  }
+  if (optimizeData.diagnostics.candidatesWithMissingPricing.length > 0) {
+    const missingLine = `Missing candidate pricing: ${optimizeData.diagnostics.candidatesWithMissingPricing.join(", ")}`;
+    lines.push(options.useColor ? pc6.yellow(missingLine) : missingLine);
+  }
+  const legendLine = "Savings = Baseline - Hypothetical (positive means cheaper candidate)";
+  lines.push(options.useColor ? pc6.dim(legendLine) : legendLine);
+  return lines;
+}
+function toTableCells(optimizeData, options) {
+  const baselineByPeriod = new Map(
+    optimizeData.rows.filter((row) => row.rowType === "baseline").map((row) => [row.periodKey, row])
+  );
+  return optimizeData.rows.map((row) => {
+    const baselineRow = baselineByPeriod.get(row.periodKey);
+    const periodCell = options.useColor && row.periodKey === "ALL" ? pc6.bold(row.periodKey) : row.periodKey;
+    if (row.rowType === "baseline") {
+      const baselineCells = [
+        periodCell,
+        styleCandidateCell("BASELINE", "baseline", options.useColor),
+        "-",
+        formatUsd3(row.baselineCostUsd, { approximate: row.baselineCostIncomplete }),
+        "-",
+        "-"
+      ];
+      return options.includeNotesColumn ? [...baselineCells, "-"] : baselineCells;
+    }
+    const savingsCell = formatUsd3(row.savingsUsd);
+    const savingsPctCell = formatPercent(row.savingsPct);
+    const notesCell = formatNotes(row.notes);
+    const candidateCells = [
+      periodCell,
+      styleCandidateCell(row.candidateModel, "candidate", options.useColor),
+      formatUsd3(row.hypotheticalCostUsd, { approximate: row.hypotheticalCostIncomplete }),
+      formatUsd3(baselineRow?.baselineCostUsd, {
+        approximate: baselineRow?.baselineCostIncomplete === true
+      }),
+      styleDeltaCell2(row.savingsUsd, savingsCell, options.useColor),
+      styleDeltaCell2(row.savingsPct, savingsPctCell, options.useColor)
+    ];
+    return options.includeNotesColumn ? [...candidateCells, styleNotesCell(row.notes, notesCell, options.useColor)] : candidateCells;
+  });
+}
 function toMarkdownSafeCell2(value) {
   return value.replace(/\r?\n/gu, "<br>");
 }
+function toSortingUsageRows(optimizeData) {
+  return optimizeData.rows.map((row) => {
+    return {
+      rowType: "period_source",
+      periodKey: row.periodKey,
+      source: "combined",
+      models: [],
+      modelBreakdown: [],
+      inputTokens: row.inputTokens,
+      outputTokens: row.outputTokens,
+      reasoningTokens: row.reasoningTokens,
+      cacheReadTokens: row.cacheReadTokens,
+      cacheWriteTokens: row.cacheWriteTokens,
+      totalTokens: row.totalTokens,
+      costUsd: row.rowType === "baseline" ? row.baselineCostUsd : row.hypotheticalCostUsd,
+      costIncomplete: row.rowType === "baseline" ? row.baselineCostIncomplete : row.hypotheticalCostIncomplete
+    };
+  });
+}
+function resolveCandidateColumnWidth(tableCells) {
+  return tableCells.reduce((maxWidth, row) => {
+    const candidateValue = row[1] ?? "";
+    return Math.max(maxWidth, visibleWidth(candidateValue));
+  }, visibleWidth(optimizeTableHeadersWithNotes[1]));
+}
+function resolveIncludeNotesColumn(optimizeData) {
+  return optimizeData.rows.some(
+    (row) => row.rowType === "candidate" && row.notes !== void 0 && row.notes.length > 0
+  );
+}
+function renderTerminalOptimizeReport(optimizeData, options) {
+  const useColor = options.useColor ?? shouldUseColorByDefault();
+  const includeNotesColumn = resolveIncludeNotesColumn(optimizeData);
+  const tableCells = toTableCells(optimizeData, { useColor, includeNotesColumn });
+  const candidateColumnWidth = resolveCandidateColumnWidth(tableCells);
+  const contextLines = resolveTerminalContextLines(optimizeData, { useColor });
+  const headerCells = includeNotesColumn ? [...optimizeTableHeadersWithNotes] : [...optimizeTableHeadersWithoutNotes];
+  const outputLines = [];
+  outputLines.push(
+    renderReportHeader({
+      title: getReportTitle2(options.granularity),
+      useColor
+    })
+  );
+  outputLines.push("");
+  outputLines.push(...contextLines);
+  outputLines.push("");
+  outputLines.push(
+    renderUnicodeTable({
+      headerCells,
+      bodyRows: tableCells,
+      measureHeaderCells: headerCells,
+      measureBodyRows: tableCells,
+      usageRows: toSortingUsageRows(optimizeData),
+      tableLayout: "compact",
+      modelsColumnIndex: 1,
+      modelsColumnWidth: candidateColumnWidth
+    })
+  );
+  return outputLines.join("\n");
+}
+function renderMarkdownOptimizeReport(optimizeData) {
+  const includeNotesColumn = resolveIncludeNotesColumn(optimizeData);
+  const headerCells = includeNotesColumn ? [...optimizeTableHeadersWithNotes] : [...optimizeTableHeadersWithoutNotes];
+  const bodyRows = toTableCells(optimizeData, {
+    useColor: false,
+    includeNotesColumn
+  }).map((row) => row.map((cell) => toMarkdownSafeCell2(cell)));
+  const tableRows = [headerCells, ...bodyRows];
+  const alignment2 = headerCells.map((_, index) => index <= 1 ? "l" : "r");
+  return markdownTable2(tableRows, { align: alignment2 });
+}
+function renderOptimizeReport(optimizeData, format, options) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(optimizeData.rows, null, 2);
+    case "markdown":
+      return renderMarkdownOptimizeReport(optimizeData);
+    case "terminal":
+      return renderTerminalOptimizeReport(optimizeData, options);
+  }
+}
+
+// src/optimize/aggregate-counterfactual.ts
+var USD_PRECISION_SCALE3 = 1e12;
+function roundUsd(value) {
+  return Math.round(value * USD_PRECISION_SCALE3) / USD_PRECISION_SCALE3;
+}
+function hasZeroBillableTokenBuckets(totals) {
+  return totals.inputTokens === 0 && totals.outputTokens === 0 && totals.reasoningTokens === 0 && totals.cacheReadTokens === 0 && totals.cacheWriteTokens === 0;
+}
+function parseCandidateModelsRaw(candidateModel) {
+  if (!candidateModel || Array.isArray(candidateModel) && candidateModel.length === 0) {
+    throw new Error("At least one --candidate-model is required");
+  }
+  const normalizedCandidates = (Array.isArray(candidateModel) ? candidateModel : [candidateModel]).flatMap((candidate) => candidate.split(",")).map((candidate) => candidate.trim().toLowerCase()).filter((candidate) => candidate.length > 0);
+  if (normalizedCandidates.length === 0) {
+    throw new Error("--candidate-model must contain at least one non-empty model name");
+  }
+  return [...new Set(normalizedCandidates)];
+}
+function normalizeCandidateModels(candidateModel) {
+  return parseCandidateModelsRaw(candidateModel);
+}
+function parseTopOption(top) {
+  if (top === void 0) {
+    return void 0;
+  }
+  const normalized = top.trim();
+  const parsed = Number.parseInt(normalized, 10);
+  if (!/^\d+$/u.test(normalized) || Number.isNaN(parsed) || parsed < 1) {
+    throw new Error("--top must be a positive integer");
+  }
+  return parsed;
+}
+function toBaselineRow(period, provider) {
+  return {
+    rowType: "baseline",
+    periodKey: period.periodKey,
+    provider,
+    inputTokens: period.inputTokens,
+    outputTokens: period.outputTokens,
+    reasoningTokens: period.reasoningTokens,
+    cacheReadTokens: period.cacheReadTokens,
+    cacheWriteTokens: period.cacheWriteTokens,
+    totalTokens: period.totalTokens,
+    baselineCostUsd: period.baselineCostUsd,
+    baselineCostIncomplete: period.baselineCostIncomplete
+  };
+}
+function createSyntheticEvent(period) {
+  return {
+    source: "pi",
+    sessionId: "optimize-period",
+    timestamp: "1970-01-01T00:00:00.000Z",
+    provider: void 0,
+    model: "synthetic",
+    inputTokens: period.inputTokens,
+    outputTokens: period.outputTokens,
+    reasoningTokens: period.reasoningTokens,
+    cacheReadTokens: period.cacheReadTokens,
+    cacheWriteTokens: period.cacheWriteTokens,
+    totalTokens: period.totalTokens,
+    costMode: "estimated",
+    costUsd: void 0
+  };
+}
+function withNotes(notes) {
+  if (notes.size === 0) {
+    return void 0;
+  }
+  return [...notes].sort(compareByCodePoint);
+}
+function evaluateCandidateForPeriod(period, provider, candidateModel, pricingSource) {
+  const notes = /* @__PURE__ */ new Set();
+  const zeroBillableTokens = hasZeroBillableTokenBuckets(period);
+  const candidateResolvedModel = pricingSource ? pricingSource.resolveModelAlias(candidateModel) : candidateModel;
+  const pricing = pricingSource ? pricingSource.getPricing(candidateResolvedModel) : void 0;
+  let hypotheticalCostUsd;
+  let hypotheticalCostIncomplete = false;
+  if (!pricing) {
+    if (zeroBillableTokens) {
+      hypotheticalCostUsd = 0;
+    } else {
+      hypotheticalCostUsd = void 0;
+      hypotheticalCostIncomplete = true;
+      notes.add("missing_pricing");
+    }
+  } else {
+    hypotheticalCostUsd = roundUsd(
+      calculateEstimatedCostUsd(createSyntheticEvent(period), pricing)
+    );
+  }
+  let savingsUsd;
+  let savingsPct;
+  let hasBaselineTokenMismatch = false;
+  if (period.baselineCostIncomplete || period.baselineCostUsd === void 0) {
+    notes.add("baseline_incomplete");
+  } else if (zeroBillableTokens && period.baselineCostUsd > 0) {
+    notes.add("baseline_tokens_missing");
+    hasBaselineTokenMismatch = true;
+  } else if (hypotheticalCostUsd !== void 0) {
+    savingsUsd = roundUsd(period.baselineCostUsd - hypotheticalCostUsd);
+    savingsPct = period.baselineCostUsd === 0 ? void 0 : savingsUsd / period.baselineCostUsd;
+  }
+  return {
+    candidateRow: {
+      rowType: "candidate",
+      periodKey: period.periodKey,
+      provider,
+      inputTokens: period.inputTokens,
+      outputTokens: period.outputTokens,
+      reasoningTokens: period.reasoningTokens,
+      cacheReadTokens: period.cacheReadTokens,
+      cacheWriteTokens: period.cacheWriteTokens,
+      totalTokens: period.totalTokens,
+      candidateModel,
+      candidateResolvedModel,
+      hypotheticalCostUsd,
+      hypotheticalCostIncomplete,
+      savingsUsd,
+      savingsPct,
+      notes: withNotes(notes)
+    },
+    missingPricing: notes.has("missing_pricing"),
+    hasBaselineTokenMismatch
+  };
+}
+function compareCandidateRank(left, right) {
+  if (left.hypotheticalCostUsd === void 0 && right.hypotheticalCostUsd !== void 0) {
+    return 1;
+  }
+  if (left.hypotheticalCostUsd !== void 0 && right.hypotheticalCostUsd === void 0) {
+    return -1;
+  }
+  if (left.hypotheticalCostUsd !== void 0 && right.hypotheticalCostUsd !== void 0) {
+    if (left.hypotheticalCostUsd !== right.hypotheticalCostUsd) {
+      return left.hypotheticalCostUsd - right.hypotheticalCostUsd;
+    }
+  }
+  return compareByCodePoint(left.candidateModel, right.candidateModel);
+}
+function resolveBaselinePeriods(usageRows) {
+  const periodRows = /* @__PURE__ */ new Map();
+  let grandTotalRow;
+  for (const row of usageRows) {
+    if (row.rowType === "grand_total") {
+      grandTotalRow = row;
+      continue;
+    }
+    if (row.rowType === "period_combined") {
+      periodRows.set(row.periodKey, row);
+      continue;
+    }
+    if (!periodRows.has(row.periodKey)) {
+      periodRows.set(row.periodKey, row);
+    }
+  }
+  const sortedPeriodKeys = [...periodRows.keys()].sort(compareByCodePoint);
+  const periods = sortedPeriodKeys.map((periodKey) => {
+    const row = periodRows.get(periodKey);
+    if (!row) {
+      throw new Error(`Missing baseline row for period ${periodKey}`);
+    }
+    return {
+      periodKey,
+      inputTokens: row.inputTokens,
+      outputTokens: row.outputTokens,
+      reasoningTokens: row.reasoningTokens,
+      cacheReadTokens: row.cacheReadTokens,
+      cacheWriteTokens: row.cacheWriteTokens,
+      totalTokens: row.totalTokens,
+      baselineCostUsd: row.costUsd,
+      baselineCostIncomplete: row.costIncomplete === true
+    };
+  });
+  const allRow = grandTotalRow;
+  if (allRow) {
+    periods.push({
+      periodKey: "ALL",
+      inputTokens: allRow.inputTokens,
+      outputTokens: allRow.outputTokens,
+      reasoningTokens: allRow.reasoningTokens,
+      cacheReadTokens: allRow.cacheReadTokens,
+      cacheWriteTokens: allRow.cacheWriteTokens,
+      totalTokens: allRow.totalTokens,
+      baselineCostUsd: allRow.costUsd,
+      baselineCostIncomplete: allRow.costIncomplete === true
+    });
+  } else {
+    periods.push({
+      periodKey: "ALL",
+      inputTokens: 0,
+      outputTokens: 0,
+      reasoningTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      totalTokens: 0,
+      baselineCostUsd: 0,
+      baselineCostIncomplete: false
+    });
+  }
+  return periods;
+}
+function buildWarning(periodKeys) {
+  if (periodKeys.length === 0) {
+    return void 0;
+  }
+  const sortedPeriodKeys = [...new Set(periodKeys)].sort(compareByCodePoint);
+  return `Baseline cost exists for zero-token periods (${sortedPeriodKeys.join(", ")}); savings were omitted.`;
+}
+function buildCounterfactualRows(input) {
+  const baselinePeriods = resolveBaselinePeriods(input.usageRows);
+  const allPeriod = baselinePeriods.find((period) => period.periodKey === "ALL");
+  if (!allPeriod) {
+    throw new Error("Missing ALL baseline totals");
+  }
+  const allPeriodEvaluations = input.candidateModels.map(
+    (candidateModel) => evaluateCandidateForPeriod(allPeriod, input.provider, candidateModel, input.pricingSource)
+  );
+  const rankedCandidates = allPeriodEvaluations.map(({ candidateRow }) => ({
+    candidateModel: candidateRow.candidateModel,
+    hypotheticalCostUsd: candidateRow.hypotheticalCostUsd
+  })).sort(compareCandidateRank).map((candidate) => candidate.candidateModel);
+  const selectedCandidates = input.top === void 0 ? rankedCandidates : rankedCandidates.slice(0, input.top);
+  const allEvaluationByCandidate = new Map(
+    allPeriodEvaluations.map((evaluation) => [evaluation.candidateRow.candidateModel, evaluation])
+  );
+  const candidatesWithMissingPricing = input.candidateModels.filter(
+    (candidateModel) => allEvaluationByCandidate.get(candidateModel)?.missingPricing === true
+  ).sort(compareByCodePoint);
+  const warningPeriods = [];
+  const rows = [];
+  for (const period of baselinePeriods) {
+    rows.push(toBaselineRow(period, input.provider));
+    for (const candidateModel of selectedCandidates) {
+      const resolvedEvaluation = period.periodKey === "ALL" ? allEvaluationByCandidate.get(candidateModel) : evaluateCandidateForPeriod(period, input.provider, candidateModel, input.pricingSource);
+      if (!resolvedEvaluation) {
+        continue;
+      }
+      if (resolvedEvaluation.hasBaselineTokenMismatch) {
+        warningPeriods.push(period.periodKey);
+      }
+      rows.push(resolvedEvaluation.candidateRow);
+    }
+  }
+  return {
+    rows,
+    candidatesWithMissingPricing,
+    baselineCostIncomplete: allPeriod.baselineCostIncomplete,
+    warning: buildWarning(warningPeriods)
+  };
+}
+
+// src/cli/build-optimize-data.ts
+function resolveOptimizeProvider(providers, providerFilter) {
+  const distinctProviders = [...providers].sort(compareByCodePoint);
+  const normalizedProviderFilter = normalizeProviderFilter(providerFilter);
+  if (distinctProviders.length > 1) {
+    if (normalizedProviderFilter) {
+      const matchingProviders = distinctProviders.filter(
+        (provider) => provider.includes(normalizedProviderFilter)
+      );
+      if (matchingProviders.includes(normalizedProviderFilter)) {
+        return normalizedProviderFilter;
+      }
+      if (matchingProviders.length === 1) {
+        return matchingProviders[0];
+      }
+      if (matchingProviders.length === 0) {
+        throw new Error(
+          `Optimize --provider "${normalizedProviderFilter}" matched no providers. Available providers: ${distinctProviders.join(", ")}.`
+        );
+      }
+      if (matchingProviders.length > 1) {
+        throw new Error(
+          `Optimize matched multiple providers for --provider "${normalizedProviderFilter}": ${matchingProviders.join(", ")}. Supply a more specific --provider value.`
+        );
+      }
+    }
+    throw new Error(
+      `Optimize requires a single provider; found providers: ${distinctProviders.join(", ")}. Narrow with --provider.`
+    );
+  }
+  if (distinctProviders.length === 1) {
+    return distinctProviders[0];
+  }
+  return normalizedProviderFilter ?? "unknown";
+}
+async function buildOptimizeData(granularity, options, deps = {}) {
+  const candidateModels = normalizeCandidateModels(options.candidateModel);
+  const top = parseTopOption(options.top);
+  const dataset = await buildUsageEventDataset(options, deps);
+  const detectedProviders = new Set(
+    dataset.filteredEvents.map((event) => normalizeProviderFilter(event.provider)).filter((provider2) => provider2 !== void 0)
+  );
+  const provider = resolveOptimizeProvider(
+    detectedProviders,
+    dataset.normalizedInputs.providerFilter
+  );
+  const { pricedEvents, pricingOrigin, pricingWarning, pricingSource } = await applyPricingToUsageEventDataset(dataset, deps, "force");
+  const usageRows = aggregateUsage(pricedEvents, {
+    granularity,
+    timezone: dataset.normalizedInputs.timezone,
+    sourceOrder: dataset.adaptersToParse.map((adapter) => adapter.id)
+  });
+  const counterfactual = buildCounterfactualRows({
+    usageRows,
+    provider,
+    candidateModels,
+    pricingSource,
+    top
+  });
+  const usageDiagnostics = buildUsageDiagnostics({
+    adaptersToParse: dataset.adaptersToParse,
+    successfulParseResults: dataset.successfulParseResults,
+    sourceFailures: dataset.sourceFailures,
+    pricingOrigin,
+    pricingWarning,
+    activeEnvOverrides: dataset.readEnvVarOverrides(),
+    timezone: dataset.normalizedInputs.timezone
+  });
+  return {
+    rows: counterfactual.rows,
+    diagnostics: {
+      usage: usageDiagnostics,
+      provider,
+      baselineCostIncomplete: counterfactual.baselineCostIncomplete,
+      candidatesWithMissingPricing: counterfactual.candidatesWithMissingPricing,
+      warning: counterfactual.warning
+    }
+  };
+}
+
+// src/cli/run-optimize-report.ts
+function validateOutputFormatOptions2(options) {
+  if (options.markdown && options.json) {
+    throw new Error("Choose either --markdown or --json, not both");
+  }
+}
+function resolveReportFormat2(options) {
+  if (options.json) {
+    return "json";
+  }
+  if (options.markdown) {
+    return "markdown";
+  }
+  return "terminal";
+}
+async function prepareOptimizeReport(granularity, options) {
+  validateOutputFormatOptions2(options);
+  const optimizeData = await buildOptimizeData(granularity, options);
+  const format = resolveReportFormat2(options);
+  return {
+    format,
+    diagnostics: optimizeData.diagnostics,
+    candidateCount: optimizeData.rows.filter(
+      (row) => row.rowType === "candidate" && row.periodKey === "ALL"
+    ).length,
+    output: renderOptimizeReport(optimizeData, format, {
+      granularity
+    })
+  };
+}
+async function runOptimizeReport(granularity, options) {
+  const preparedReport = await prepareOptimizeReport(granularity, options);
+  emitDiagnostics(preparedReport.diagnostics.usage, logger);
+  emitEnvVarOverrides(preparedReport.diagnostics.usage.activeEnvOverrides, logger);
+  logger.info(
+    `Optimize provider scope: ${preparedReport.diagnostics.provider}; candidate(s): ${preparedReport.candidateCount}`
+  );
+  if (preparedReport.diagnostics.candidatesWithMissingPricing.length > 0) {
+    logger.warn(
+      `Missing pricing for candidate model(s): ${preparedReport.diagnostics.candidatesWithMissingPricing.join(", ")}`
+    );
+  }
+  if (preparedReport.diagnostics.warning) {
+    logger.warn(preparedReport.diagnostics.warning);
+  }
+  if (preparedReport.format === "terminal") {
+    warnIfTerminalTableOverflows(preparedReport.output, (message) => {
+      logger.warn(message);
+    });
+  }
+  console.log(preparedReport.output);
+}
+
+// src/render/markdown-table.ts
+import { markdownTable as markdownTable3 } from "markdown-table";
+var alignment = ["l", "l", "l", "r", "r", "r", "r", "r", "r", "r"];
+function toMarkdownSafeCell3(value) {
+  return value.replace(/\r?\n/gu, "<br>");
+}
 function renderMarkdownTable(rows, options = {}) {
   const tableLayout = options.tableLayout ?? "compact";
   const bodyRows = toUsageTableCells(rows, { layout: tableLayout }).map(
-    (row) => row.map((cell) => toMarkdownSafeCell2(cell))
+    (row) => row.map((cell) => toMarkdownSafeCell3(cell))
   );
   const tableRows = [Array.from(usageTableHeaders), ...bodyRows];
-  return markdownTable2(tableRows, {
+  return markdownTable3(tableRows, {
     align: alignment
   });
 }
 
 // src/render/render-usage-report.ts
-function getReportTitle2(granularity) {
+function getReportTitle3(granularity) {
   switch (granularity) {
     case "daily":
       return "Daily Token Usage Report";
@@ -6117,7 +6890,7 @@ function renderTerminalUsageReport(usageData, options) {
   const tableLayout = options.tableLayout ?? "compact";
   outputLines.push(
     renderReportHeader({
-      title: getReportTitle2(options.granularity),
+      title: getReportTitle3(options.granularity),
       useColor
     })
   );
@@ -6138,12 +6911,12 @@ function renderUsageReport(usageData, format, options) {
 }
 
 // src/cli/run-usage-report.ts
-function validateOutputFormatOptions2(options) {
+function validateOutputFormatOptions3(options) {
   if (options.markdown && options.json) {
     throw new Error("Choose either --markdown or --json, not both");
   }
 }
-function resolveReportFormat2(options) {
+function resolveReportFormat3(options) {
   if (options.json) {
     return "json";
   }
@@ -6156,9 +6929,9 @@ function resolveTableLayout(options) {
   return options.perModelColumns ? "per_model_columns" : "compact";
 }
 async function prepareUsageReport(granularity, options) {
-  validateOutputFormatOptions2(options);
+  validateOutputFormatOptions3(options);
   const usageData = await buildUsageData(granularity, options);
-  const format = resolveReportFormat2(options);
+  const format = resolveReportFormat3(options);
   return {
     format,
     diagnostics: usageData.diagnostics,
@@ -6206,7 +6979,10 @@ function addSharedOptions(command, options = {}) {
     `Filter by source id (repeatable or comma-separated, supported sources ${supportedSourcesSummary})`,
     collectRepeatedOption,
     []
-  ).option("--since <YYYY-MM-DD>", "Inclusive start date filter").option("--until <YYYY-MM-DD>", "Inclusive end date filter").option("--timezone <iana>", "Timezone for bucketing", defaultTimezone).option("--provider <name>", "Provider filter (substring match, optional)").option(
+  ).option("--since <YYYY-MM-DD>", "Inclusive start date filter").option("--until <YYYY-MM-DD>", "Inclusive end date filter").option("--timezone <iana>", "Timezone for bucketing", defaultTimezone).option(
+    "--provider <name>",
+    "Billing-provider filter (substring match, optional; e.g. openai, anthropic, google)"
+  ).option(
     "--model <name>",
     "Filter by model (repeatable/comma-separated; exact when exact match exists after source/provider/date filters, otherwise substring)",
     collectRepeatedOption,
@@ -6254,6 +7030,18 @@ function createEfficiencyCommand() {
   });
   return command;
 }
+function createOptimizeCommand() {
+  const command = new Command("optimize");
+  addSharedOptions(command, { includePerModelColumns: false }).argument("<granularity>", "Granularity: daily | weekly | monthly", parseGranularityArgument).option(
+    "--candidate-model <name>",
+    "Candidate model for counterfactual pricing (repeatable or comma-separated)",
+    collectRepeatedOption,
+    []
+  ).option("--top <n>", "Show only the top N cheapest candidates (positive integer)").description("Show counterfactual pricing report for candidate model(s)").action(async (granularity, options) => {
+    await runOptimizeReport(granularity, options);
+  });
+  return command;
+}
 function rootDescription() {
   const supportedSourceIds = getSupportedSourceIds();
   const allowedSourcesLabel = getAllowedSourcesLabel(supportedSourceIds);
@@ -6273,12 +7061,13 @@ function rootDescription() {
     "  $ llm-usage daily --source-dir pi=/tmp/pi-sessions --source-dir gemini=/tmp/.gemini --source-dir droid=/tmp/droid-sessions",
     "  $ llm-usage daily --pi-dir /tmp/pi-sessions --gemini-dir /tmp/.gemini --droid-dir /tmp/droid-sessions",
     "  $ llm-usage efficiency weekly --repo-dir /path/to/repo --json",
+    "  $ llm-usage optimize monthly --provider openai --candidate-model gpt-4.1 --candidate-model gpt-5-codex --json",
     "  $ npx --yes llm-usage-metrics@latest daily"
   ].join("\n");
 }
 function createCli(options = {}) {
   const program = new Command();
-  program.name("llm-usage").description(rootDescription()).version(options.version ?? "0.0.0").showHelpAfterError().addCommand(createCommand("daily")).addCommand(createCommand("weekly")).addCommand(createCommand("monthly")).addCommand(createEfficiencyCommand());
+  program.name("llm-usage").description(rootDescription()).version(options.version ?? "0.0.0").showHelpAfterError().addCommand(createCommand("daily")).addCommand(createCommand("weekly")).addCommand(createCommand("monthly")).addCommand(createEfficiencyCommand()).addCommand(createOptimizeCommand());
   return program;
 }