Skip to content

Commit 99bbbba

Browse files
jay-tauCopilot
andcommitted
refactor(cli): rename --mode api-equiv to --mode api
`api-equiv` was a wordy spelling of the same concept. The shorter `api` reads better in CLI help, in docs, and at the command line, and there's no naming conflict to defend against now that `--mode credits` has been removed. Note for Copilot specifically: `auto` is GitHub's bill against your allotment (AI Credits × $0.01, or premium-request × $0.04 for pre-cutover sessions). `api` is the *hypothetical* equivalent of calling Anthropic / OpenAI / Google directly at LiteLLM token pricing — useful for justifying the Copilot subscription. Changes: - `ccusage-cli/src/parser.rs`: accept `"api"` instead of `"api-equiv"`; updated tests now reject the old spelling (`parse_cost_mode("api-equiv")` returns an error). - `ccusage-cli/src/cli-help.json` and `help_codegen.rs`: rename in the `--mode` choices list rendered in `--help`. - `config_schema.rs`: rename `ConfigCostMode::ApiEquiv` to `Api`, drop the explicit serde rename so it surfaces as `"api"` via the enum's `rename_all = "lowercase"`. - `config.rs`: updated `From<ConfigCostMode>` arm. - `adapter/copilot/loader.rs`: comment updates only (`Calculate / api` in the dispatch table and inline comments). - Regenerated JSON schemas (`apps/ccusage/config-schema.json` and the gitignored `docs/public/config-schema.json` mirror) and accepted the schema snapshot diff (only the literal `"api-equiv"` → `"api"` swap in each occurrence). - Docs: `docs/guide/copilot/index.md`, `docs/guide/cost-modes.md`, `docs/guide/cli-options.md`, and the adapter README all updated to use `api` instead of `api-equiv`. Verified: 327 workspace tests pass. `./target/release/ccusage copilot daily --mode api --json --offline` returns 74 days / $7,561.16 (api-equivalent), confirming the alias still routes to the same `Calculate` code path. `--mode api-equiv` is now rejected with "Invalid cost mode 'api-equiv'". Refs ccusage#1174 Co-authored-by: Copilot <[email protected]>
1 parent e77dc73 commit 99bbbba

12 files changed

Lines changed: 113 additions & 111 deletions

File tree

‎apps/ccusage/config-schema.json‎

Lines changed: 69 additions & 69 deletions
Large diffs are not rendered by default.

‎docs/guide/cli-options.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,8 @@ ccusage daily --mode auto
4949
# Calculate mode - always calculate from tokens
5050
ccusage daily --mode calculate
5151

52-
# api-equiv - alias for `calculate` (same behavior)
53-
ccusage daily --mode api-equiv
52+
# api - alias for `calculate` (same behavior)
53+
ccusage daily --mode api
5454

5555
# Display mode - only show pre-calculated costUSD
5656
ccusage daily --mode display

‎docs/guide/copilot/index.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,13 +51,13 @@ These views support `--json` for structured output, `--compact` for narrow termi
5151

5252
## Pricing modes
5353

54-
`ccusage copilot` supports the standard cost modes plus an `api-equiv` discoverability alias. For Copilot, the modes map to billing realities as follows:
54+
`ccusage copilot` supports the standard cost modes plus an `api` discoverability alias. For Copilot, the modes map to billing realities as follows:
5555

5656
| Mode | What it shows for Copilot |
5757
|---|---|
5858
| `auto` (default) | **True bill, era-aware**: AI Credits for post-cutover sessions (CLI ≥ 1.0.40), premium-request × $0.04 for pre-cutover sessions, token-priced for sessions with neither billing field |
5959
| `display` | Source-precomputed only: AI Credits → premium-requests → `$0.00`. No token-priced fallback |
60-
| `calculate` / `api-equiv` | Always LiteLLM token pricing — what the same usage would have cost via the underlying provider's API |
60+
| `calculate` / `api` | Always LiteLLM token pricing — what the same usage would have cost via the underlying provider's API |
6161

6262
Why era-aware? GitHub Copilot switched billing models on June 1, 2026: pre-cutover sessions were billed as "premium requests" with per-model multipliers at $0.04 per overage request; post-cutover sessions bill as AI Credits at $0.01 per credit. The Copilot CLI records each session's own billing data, so `auto` reports what GitHub actually charged you for that session — whichever era it belongs to.
6363

@@ -67,7 +67,7 @@ ccusage copilot daily
6767

6868
# API-equivalent: what direct Anthropic/OpenAI/Google calls would have cost.
6969
# Useful for justifying the Copilot subscription.
70-
ccusage copilot daily --mode api-equiv
70+
ccusage copilot daily --mode api
7171

7272
# Source-precomputed only: walks AIU → premium-requests → $0. No fallback.
7373
ccusage copilot daily --mode display
@@ -85,7 +85,7 @@ See [Cost Modes](/guide/cost-modes) for the full mode reference.
8585
- **Cache tokens** — cache read and cache creation tokens are counted from the source's `cacheReadTokens` / `cacheWriteTokens` fields.
8686
- **Reasoning tokens** — provider-dependent. For OpenAI (`gpt-*`) and Anthropic (`claude-*`) models reasoning is already inside `outputTokens` and is not double-counted. For Google (`gemini-*`) models reasoning is reported separately and is summed into the output cost bucket.
8787
- **Credits** — when present, `totalNanoAiu` is divided by 10⁹ to get the AI Credit count (`1 credit = $0.01`). Always surfaced in JSON. Drives the cost figure under `auto` / `display` when present.
88-
- **Pricing** — for `calculate` / `api-equiv` mode, costs are computed from LiteLLM pricing data using a normalized form of the model name. The raw name (e.g. `claude-opus-4.7-1m-internal`) is preserved in JSON, the table's `Models` column, and `modelsUsed`.
88+
- **Pricing** — for `calculate` / `api` mode, costs are computed from LiteLLM pricing data using a normalized form of the model name. The raw name (e.g. `claude-opus-4.7-1m-internal`) is preserved in JSON, the table's `Models` column, and `modelsUsed`.
8989

9090
## Environment Variables
9191

‎docs/guide/cost-modes.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ccusage supports three cost calculation modes to handle various scenarios and da
77
Claude Code stores usage data in JSONL files with both token counts and pre-calculated cost information. ccusage can handle this data in different ways depending on your needs:
88

99
- **`auto`** - Smart mode using the best available data
10-
- **`calculate`** (also aliased as **`api-equiv`**) - Always calculate from token counts (LiteLLM pricing)
10+
- **`calculate`** (also aliased as **`api`**) - Always calculate from token counts (LiteLLM pricing)
1111
- **`display`** - Only show pre-calculated costs
1212

1313
## Mode Details
@@ -61,11 +61,11 @@ The `calculate` mode always computes costs from token counts using model pricing
6161
ccusage daily --mode calculate
6262
ccusage monthly --mode calculate --breakdown
6363

64-
# `api-equiv` is an alias for `calculate` (same behavior — bills from
64+
# `api` is an alias for `calculate` (same behavior — bills from
6565
# LiteLLM token pricing). The shorter, intent-revealing name is useful
6666
# for Copilot reports where you want to contrast the "API-equivalent"
6767
# cost against `auto`'s "what Copilot actually billed" figure.
68-
ccusage copilot daily --mode api-equiv
68+
ccusage copilot daily --mode api
6969
```
7070

7171
#### How it works:

‎rust/crates/ccusage-cli/src/cli-help.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -250,7 +250,7 @@
250250
"flags": "-m, --mode [mode]",
251251
"description": "Cost calculation mode",
252252
"default": "auto",
253-
"choices": ["auto", "calculate", "display", "api-equiv"]
253+
"choices": ["auto", "calculate", "display", "api"]
254254
},
255255
{
256256
"flags": "-d, --debug",

‎rust/crates/ccusage-cli/src/help_codegen.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -366,13 +366,13 @@ mod tests {
366366
"flags": "--mode <MODE>",
367367
"description": "Cost calculation mode",
368368
"default": "auto",
369-
"choices": ["auto", "calculate", "display", "api-equiv"]
369+
"choices": ["auto", "calculate", "display", "api"]
370370
}
371371
]);
372372

373373
let output = render_options(&options);
374374

375375
assert!(output.contains("default: auto"));
376-
assert!(output.contains("choices: auto | calculate | display | api-equiv"));
376+
assert!(output.contains("choices: auto | calculate | display | api"));
377377
}
378378
}

‎rust/crates/ccusage-cli/src/parser.rs‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -862,11 +862,12 @@ fn is_shared_flag(arg: &str) -> bool {
862862
fn parse_cost_mode(value: &str) -> Result<CostMode, String> {
863863
match value {
864864
"auto" => Ok(CostMode::Auto),
865-
// `api-equiv` is a discoverability alias for `calculate` — both
866-
// bill from LiteLLM token pricing. The alias names the
867-
// api-equivalent intent explicitly in `--help` without expanding
868-
// the `CostMode` enum.
869-
"calculate" | "api-equiv" => Ok(CostMode::Calculate),
865+
// `api` is a discoverability alias for `calculate` — both bill
866+
// from LiteLLM token pricing. The shorter, intent-revealing name
867+
// is useful for Copilot reports where users want to contrast the
868+
// "API-equivalent" cost against `auto`'s "what Copilot actually
869+
// billed" figure.
870+
"calculate" | "api" => Ok(CostMode::Calculate),
870871
"display" => Ok(CostMode::Display),
871872
_ => Err(format!("Invalid cost mode '{value}'")),
872873
}
@@ -954,17 +955,19 @@ mod tests {
954955
}
955956

956957
#[test]
957-
fn parse_cost_mode_api_equiv_aliases_calculate() {
958-
// `api-equiv` is a discoverability alias for `calculate` — both
959-
// bill from LiteLLM token pricing. Surfaces the api-equivalent
960-
// intent in `--help` without expanding the `CostMode` enum.
961-
assert_eq!(parse_cost_mode("api-equiv"), Ok(CostMode::Calculate));
958+
fn parse_cost_mode_api_aliases_calculate() {
959+
// `api` is a discoverability alias for `calculate` — both bill
960+
// from LiteLLM token pricing. Surfaces the api-equivalent intent
961+
// in `--help` without expanding the `CostMode` enum.
962+
assert_eq!(parse_cost_mode("api"), Ok(CostMode::Calculate));
962963
}
963964

964965
#[test]
965966
fn parse_cost_mode_rejects_unknown_values() {
966967
assert!(parse_cost_mode("invalid").is_err());
967968
assert!(parse_cost_mode("").is_err());
968-
assert!(parse_cost_mode("API-EQUIV").is_err(), "case-sensitive");
969+
assert!(parse_cost_mode("API").is_err(), "case-sensitive");
970+
// Old pre-rename spelling is no longer accepted.
971+
assert!(parse_cost_mode("api-equiv").is_err());
969972
}
970973
}

‎rust/crates/ccusage/src/adapter/copilot/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ Rules:
9393
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9494
| `auto` | True bill, era-aware: AIU when present (post-cutover) → premium-requests × $0.04 when present (pre-cutover) → token-priced via LiteLLM (no billing fields). The default. Free-tier pre-cutover rows (`requests.cost == 0`) bill as $0. |
9595
| `display`| Source-precomputed only: AIU → premium-requests → $0. No token-priced fallback. |
96-
| `calculate` / `api-equiv` | Always token-priced via LiteLLM (`normalize_copilot_model()` applied at both `calculate_cost_for_usage` and `missing_pricing_model_for_usage` call sites). |
96+
| `calculate` / `api` | Always token-priced via LiteLLM (`normalize_copilot_model()` applied at both `calculate_cost_for_usage` and `missing_pricing_model_for_usage` call sites). |
9797

9898
The era-aware default reflects that GitHub Copilot switched billing models on
9999
June 1, 2026: pre-cutover sessions were billed in "premium requests" with

‎rust/crates/ccusage/src/adapter/copilot/loader.rs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -130,15 +130,15 @@ fn usage_entry_to_loaded(
130130
// * Pre-cutover (older CLI): `requests.cost × $0.04` (premium requests)
131131
//
132132
// `auto` and `display` follow this true-bill ladder; `calculate` /
133-
// `api-equiv` is always token-priced.
133+
// `api` is always token-priced.
134134
//
135135
// Behavior table:
136136
//
137137
// | AIU present | AIU absent, premium > 0 | AIU absent, premium absent or 0
138138
// -----------------|-----------------|-------------------------|--------------------------------
139139
// Auto (default) | credits × $0.01 | requests.cost × $0.04 | token-priced (or 0 for free-tier)
140140
// Display | credits × $0.01 | requests.cost × $0.04 | 0
141-
// Calculate/api-eq | token-priced | token-priced | token-priced
141+
// Calculate / api | token-priced | token-priced | token-priced
142142
let (cost, missing_pricing_model) = if entry.model.is_empty() {
143143
// Aggregate-credit synthetic rows carry no model. Modes that honor
144144
// source-precomputed cost (Auto / Display) bill from the aggregate
@@ -174,7 +174,7 @@ fn usage_entry_to_loaded(
174174
CostMode::Auto | CostMode::Calculate => {
175175
// Token-priced via LiteLLM. For Auto this is the last-resort
176176
// fallback when the session ships neither AIU nor
177-
// premium-request data; for Calculate / api-equiv it is the
177+
// premium-request data; for Calculate / api it is the
178178
// mode's whole purpose. Compute the normalized model name
179179
// ONCE and feed it to BOTH pricing call sites — without
180180
// normalizing at `missing_pricing_model_for_usage`,
@@ -709,7 +709,7 @@ mod tests {
709709

710710
#[test]
711711
fn calculate_mode_uses_token_pricing_even_with_naiu_present() {
712-
// Calculate / api-equiv always uses LiteLLM token pricing — the
712+
// Calculate / api always uses LiteLLM token pricing — the
713713
// credit channel stays informational in JSON, but cost comes from
714714
// the api-equivalent lookup.
715715
let _guard = COPILOT_ENV_LOCK.lock().unwrap();

‎rust/crates/ccusage/src/config.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -460,7 +460,7 @@ impl From<ConfigCostMode> for CostMode {
460460
fn from(value: ConfigCostMode) -> Self {
461461
match value {
462462
ConfigCostMode::Auto => Self::Auto,
463-
ConfigCostMode::Calculate | ConfigCostMode::ApiEquiv => Self::Calculate,
463+
ConfigCostMode::Calculate | ConfigCostMode::Api => Self::Calculate,
464464
ConfigCostMode::Display => Self::Display,
465465
}
466466
}

0 commit comments

Comments
 (0)