Skip to content

Commit 47d00e7

Browse files
jay-tauCopilot
andcommitted
feat(adapter/copilot): add --mode api-equiv as alias for calculate
Makes the api-equivalent intent explicit in CLI help and config files, mirroring how `--mode credits` reads in scripts. Both names resolve to `CostMode::Calculate` so there is no new enum variant, no extra match arms in adapter loaders, and no behavioral change beyond accepting the new spelling. * `parse_cost_mode` accepts `api-equiv` and maps it to `Calculate` (case-sensitive, matches the other choices). * `cli-help.json` and the help-codegen snapshot test list the new alias alongside the existing choices. * `ConfigCostMode::ApiEquiv` variant with `#[serde(rename = "api-equiv")]` so config files can use either spelling; `From` impl folds it into `CostMode::Calculate`. JSON schema snapshot updated. * Docs: `cost-modes.md`, `cli-options.md`, and the Copilot guide now list `api-equiv` alongside `calculate` and `credits`. Smoke test on real local data (74 days): --mode api-equiv: $7,561.16 --mode calculate: $7,561.16 (identical, as expected) Tests * 3 new parse_cost_mode tests cover the full choice set, the api-equiv alias resolution, and case-sensitive rejection of unknown values. This completes Piece C of ccusage#1174. Pieces A, B, and C are now all shipped. Refs ccusage#1174 Co-authored-by: Copilot <[email protected]>
1 parent 1322e4c commit 47d00e7

10 files changed

Lines changed: 210 additions & 83 deletions

File tree

‎apps/ccusage/config-schema.json‎

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

‎docs/guide/cli-options.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ 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
54+
5255
# Display mode - only show pre-calculated costUSD
5356
ccusage daily --mode display
5457

‎docs/guide/copilot/index.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,20 +68,27 @@ These views support `--json` for structured output, `--compact` for narrow termi
6868

6969
## Pricing modes
7070

71-
`ccusage copilot` supports the standard cost modes (`auto`, `calculate`, `display`) plus a Copilot-specific `credits` mode:
71+
`ccusage copilot` supports the standard cost modes (`auto`, `calculate`, `display`) plus a Copilot-specific `credits` mode and an `api-equiv` discoverability alias:
7272

7373
```bash
7474
# Default: API-equivalent cost from LiteLLM token pricing.
7575
ccusage copilot daily
7676

7777
# Credits mode: bill from GitHub Copilot's AI Credit counts ($0.01/credit).
7878
ccusage copilot daily --mode credits
79+
80+
# `api-equiv` is an alias for `calculate` — both bill from LiteLLM token
81+
# pricing. Use it when you want the api-equivalent intent to read
82+
# explicitly alongside `--mode credits` in scripts or config files.
83+
ccusage copilot daily --mode api-equiv
7984
```
8085

8186
In credits mode, ccusage reads `totalNanoAiu` from each `session.shutdown` event and converts directly to USD (`credits × $0.01`). No LiteLLM token pricing lookup happens, so newer Copilot model variants that aren't yet in the LiteLLM dataset still report correct cost. The `credits` field is also exposed in `--json` output regardless of the selected mode, so you can run with `--mode auto` and still see the raw credit counts.
8287

8388
Credit-only `session.shutdown` rows (zero tokens, zero requests, non-null `totalNanoAiu`) are kept even when the default skip rule would otherwise discard them. Identical duplicate credit-only snapshots within the same session are collapsed via content-based deduplication.
8489

90+
See [Cost Modes](/guide/cost-modes) for the full mode reference.
91+
8592
## What Gets Calculated
8693

8794
- **Token usage** — for session-state, `inputTokens` in the source schema already includes both cache reads and cache writes, so ccusage subtracts both to recover the "fresh" input bucket. For OTel, chat spans are preferred with inference logs and agent-turn logs as fallbacks.

‎docs/guide/cost-modes.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ccusage supports four cost calculation modes to handle various scenarios and dat
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`** - Always calculate from token counts
10+
- **`calculate`** (also aliased as **`api-equiv`**) - Always calculate from token counts (LiteLLM pricing)
1111
- **`display`** - Only show pre-calculated costs
1212
- **`credits`** - Bill from GitHub Copilot's AI Credit counts at `1 credit = $0.01` (Copilot-specific; other adapters fall back to `auto`)
1313

@@ -55,6 +55,12 @@ The `calculate` mode always computes costs from token counts using model pricing
5555
```bash
5656
ccusage daily --mode calculate
5757
ccusage monthly --mode calculate --breakdown
58+
59+
# `api-equiv` is an alias for `calculate` (same behavior — bills from
60+
# LiteLLM token pricing). Use it for parity in CLIs that already accept
61+
# `--mode credits`, where naming the api-equivalent intent explicitly
62+
# improves discoverability.
63+
ccusage copilot daily --mode api-equiv
5864
```
5965

6066
#### 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", "credits"]
253+
"choices": ["auto", "calculate", "display", "credits", "api-equiv"]
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", "credits"]
369+
"choices": ["auto", "calculate", "display", "credits", "api-equiv"]
370370
}
371371
]);
372372

373373
let output = render_options(&options);
374374

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

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

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -862,7 +862,11 @@ 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-
"calculate" => Ok(CostMode::Calculate),
865+
// `api-equiv` is a discoverability alias for `calculate` — both
866+
// bill from LiteLLM token pricing. The alias makes the
867+
// api-equivalent intent explicit in `--help` output alongside the
868+
// new `credits` mode, without expanding the `CostMode` enum.
869+
"calculate" | "api-equiv" => Ok(CostMode::Calculate),
866870
"display" => Ok(CostMode::Display),
867871
"credits" => Ok(CostMode::Credits),
868872
_ => Err(format!("Invalid cost mode '{value}'")),
@@ -942,4 +946,29 @@ mod tests {
942946
Some(ControlArg::Version)
943947
);
944948
}
949+
950+
#[test]
951+
fn parse_cost_mode_accepts_all_documented_values() {
952+
assert_eq!(parse_cost_mode("auto"), Ok(CostMode::Auto));
953+
assert_eq!(parse_cost_mode("calculate"), Ok(CostMode::Calculate));
954+
assert_eq!(parse_cost_mode("display"), Ok(CostMode::Display));
955+
assert_eq!(parse_cost_mode("credits"), Ok(CostMode::Credits));
956+
}
957+
958+
#[test]
959+
fn parse_cost_mode_api_equiv_aliases_calculate() {
960+
// `api-equiv` is a discoverability alias for `calculate` — both
961+
// bill from LiteLLM token pricing. The alias is intentional: users
962+
// should be able to write the api-equivalent intent explicitly
963+
// alongside the new Copilot-specific `credits` mode without needing
964+
// a new enum variant.
965+
assert_eq!(parse_cost_mode("api-equiv"), Ok(CostMode::Calculate));
966+
}
967+
968+
#[test]
969+
fn parse_cost_mode_rejects_unknown_values() {
970+
assert!(parse_cost_mode("invalid").is_err());
971+
assert!(parse_cost_mode("").is_err());
972+
assert!(parse_cost_mode("API-EQUIV").is_err(), "case-sensitive");
973+
}
945974
}

‎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 => Self::Calculate,
463+
ConfigCostMode::Calculate | ConfigCostMode::ApiEquiv => Self::Calculate,
464464
ConfigCostMode::Display => Self::Display,
465465
ConfigCostMode::Credits => Self::Credits,
466466
}

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -468,6 +468,13 @@ pub(crate) enum ConfigCostMode {
468468
Calculate,
469469
Display,
470470
Credits,
471+
// Discoverability alias for `Calculate` — both bill from LiteLLM token
472+
// pricing. Surfaces as `"api-equiv"` in the JSON schema enum alongside
473+
// the Copilot-specific `"credits"`. No doc-comment here so schemars
474+
// keeps the variant inside the flat enum rather than splitting it into
475+
// a separate `oneOf` arm.
476+
#[serde(rename = "api-equiv")]
477+
ApiEquiv,
471478
}
472479

473480
#[derive(Clone, Copy, Debug, Deserialize, JsonSchema)]

‎rust/crates/ccusage/src/snapshots/ccusage__config_schema__tests__snapshots_schema_agent_specific_option_edges.snap‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
source: crates/ccusage/src/config_schema.rs
3-
assertion_line: 1259
3+
assertion_line: 1266
44
expression: "json!({\n \"rootRef\": schema[\"$ref\"], \"rootProperties\":\n definition_properties(&schema, \"ccusage-config\"),\n \"rootAdditionalProperties\":\n schema[\"definitions\"][\"ccusage-config\"][\"additionalProperties\"],\n \"defaults\": schema_node(&schema, &[\"defaults\"]), \"rootDaily\":\n schema_node(&schema, &[\"commands\", \"daily\"]), \"claudeStatusline\":\n schema_node(&schema, &[\"claude\", \"commands\", \"statusline\"]),\n \"codexDefaults\": schema_node(&schema, &[\"codex\", \"defaults\"]),\n \"opencodeWeekly\":\n schema_node(&schema, &[\"opencode\", \"commands\", \"weekly\"]), \"piDefaults\":\n schema_node(&schema, &[\"pi\", \"defaults\"]), \"openclawDefaults\":\n schema_node(&schema, &[\"openclaw\", \"defaults\"]),\n})"
55
---
66
{
@@ -144,7 +144,8 @@ expression: "json!({\n \"rootRef\": schema[\"$ref\"], \"rootProperties\":\n
144144
"auto",
145145
"calculate",
146146
"display",
147-
"credits"
147+
"credits",
148+
"api-equiv"
148149
],
149150
"markdownDescription": "Cost calculation mode.",
150151
"type": "string"
@@ -268,7 +269,8 @@ expression: "json!({\n \"rootRef\": schema[\"$ref\"], \"rootProperties\":\n
268269
"auto",
269270
"calculate",
270271
"display",
271-
"credits"
272+
"credits",
273+
"api-equiv"
272274
],
273275
"markdownDescription": "Cost calculation mode.",
274276
"type": "string"
@@ -376,7 +378,8 @@ expression: "json!({\n \"rootRef\": schema[\"$ref\"], \"rootProperties\":\n
376378
"auto",
377379
"calculate",
378380
"display",
379-
"credits"
381+
"credits",
382+
"api-equiv"
380383
],
381384
"markdownDescription": "Cost calculation mode.",
382385
"type": "string"
@@ -492,7 +495,8 @@ expression: "json!({\n \"rootRef\": schema[\"$ref\"], \"rootProperties\":\n
492495
"auto",
493496
"calculate",
494497
"display",
495-
"credits"
498+
"credits",
499+
"api-equiv"
496500
],
497501
"markdownDescription": "Cost calculation mode.",
498502
"type": "string"
@@ -600,7 +604,8 @@ expression: "json!({\n \"rootRef\": schema[\"$ref\"], \"rootProperties\":\n
600604
"auto",
601605
"calculate",
602606
"display",
603-
"credits"
607+
"credits",
608+
"api-equiv"
604609
],
605610
"markdownDescription": "Cost calculation mode.",
606611
"type": "string"
@@ -714,7 +719,8 @@ expression: "json!({\n \"rootRef\": schema[\"$ref\"], \"rootProperties\":\n
714719
"auto",
715720
"calculate",
716721
"display",
717-
"credits"
722+
"credits",
723+
"api-equiv"
718724
],
719725
"markdownDescription": "Cost calculation mode.",
720726
"type": "string"

0 commit comments

Comments
 (0)