CLI Reference¶
This page is auto-generated from the Click command definitions. For a
step-by-step guide on using amend-commit to inject session cost trailers
into Git commits, see How to add a session cost trailer.
copilot-session-usage¶
Extract VS Code Copilot session cost KPIs from local debug logs.
Reads JSONL debug logs written by the VS Code Copilot Chat extension to compute per-session token counts, estimated USD spend, model breakdowns, duration, and subagent attribution.
Sessions are auto-discovered from the VS Code workspaceStorage directory (override with –workspace-storage). Use the subcommands below to analyze individual sessions, the latest session, or batches.
Output is controlled by –detail (minimal / compact / full) and –format (table / json / detailed). Key capabilities include per-model pricing with cache-hit discounts, threshold-aware tier switching for long-context models, multi-model session handling, subagent cost attribution, and cross-platform support (macOS, Linux, Windows, WSL2).
Usage
copilot-session-usage [OPTIONS] COMMAND [ARGS]...
Options
- --workspace-storage <PATH>¶
Override workspaceStorage directory (auto-detected by default). Required on WSL2 when VS Code runs on the Windows host.
- --agent <agent>¶
Provider to use for session discovery. ‘cli’ is not yet implemented.
- Default:
'vscode'- Options:
vscode | cli
amend-commit¶
Amend HEAD to inject accumulated session cost trailers.
Reads the VS Code Copilot debug logs for the given session IDs, computes
the accumulated per-model token counts, and amends the HEAD commit with
one Copilot-Session-Usage-Acc trailer per model plus a
Copilot-Session-Usage-AIC trailer with the total estimated cost.
When several --session-id values are provided, their costs and token
counts are merged before the trailers are built. This is useful when a
single coding change spanned multiple VS Code Copilot sessions.
Pass --with-session-id to also burn one
Copilot-Session-Usage-Session-ID trailer per session ID. This makes
it easier to rewrite commit history with commit-accurate costs later.
The current session ID is available to Copilot agents through the
VSCODE_TARGET_SESSION_LOG template variable in the editor context
(it is not an environment variable). Extract the UUID from that path
and pass it with --session-id.
Use --dry-run to preview the trailers without touching the commit.
Usage
copilot-session-usage amend-commit [OPTIONS]
Options
- --session-id <UUID>¶
Session UUID to inject cost trailers for. May be given multiple times.
- --with-session-id¶
Also inject a Copilot-Session-Usage-Session-ID trailer per session ID.
- --repo <PATH>¶
Path to the git repository (default: current directory).
- --dry-run¶
Print the trailers that would be injected without amending the commit.
analyze¶
Analyze a single session by PATH, or many sessions by –name regex.
PATH is the fastest path: no discovery needed. When –name is given instead, sessions are discovered from workspace storage, filtered by the regex and optional date range, and analyzed in one pass. Use –aggregate to roll them up into a single efficiency summary.
Usage
copilot-session-usage analyze [OPTIONS] PATH
Options
- --detail <detail>¶
minimal (identity+total only), compact (+models list, default), or full (+per-model and per-subagent breakdown). Ignored (forced to full) when –format detailed is used.
- Default:
'compact'- Options:
minimal | compact | full
- --format <format_>¶
json (machine-readable), table (human-readable), or detailed (table forced to full detail — same as –format table –detail full).
- Default:
'json'- Options:
json | table | detailed
- --output <PATH>¶
Write output to PATH instead of stdout.
- --skill-breakdown¶
Emit a per-skill cost breakdown instead of the default report.
- --tool-breakdown¶
Emit a per-skill/per-subagent tool-call count breakdown.
- --skill <NAME>¶
Filter the report to a single skill (exact or substring match).
- --title <SUBSTRING>¶
Filter sessions by title substring (case-insensitive).
- --latest¶
Analyze the most recent matching session instead of all matches.
- --name <REGEX>¶
Analyze sessions whose title matches REGEX (case-insensitive).
- --since <DATE>¶
Only sessions created after DATE (ISO 8601 with timezone).
- --until <DATE>¶
Only sessions created before DATE (ISO 8601 with timezone).
- --workspace <PATH>¶
Only consider sessions from this workspace folder.
- --aggregate¶
Aggregate all matching sessions into a single summary.
- --summary¶
Output a cost-efficiency summary instead of the full session report.
- --query <PATH>¶
Extract a single field using dot notation (e.g. .total.estimated_usd).
- --query-help¶
Print a reference of queryable fields and exit.
Arguments
- PATH¶
Optional argument
batch¶
Analyze the N most recent sessions in one invocation.
Always returns {“summary”: {…}, “sessions”: […]}: a pre-computed aggregate across all N sessions plus a per-session array shaped by –detail. Much faster than N separate id invocations.
Usage
copilot-session-usage batch [OPTIONS] N
Options
- --detail <detail>¶
minimal (identity+total only), compact (+models list, default), or full (+per-model and per-subagent breakdown). Ignored (forced to full) when –format detailed is used.
- Default:
'compact'- Options:
minimal | compact | full
- --format <format_>¶
json (machine-readable), table (human-readable), or detailed (table forced to full detail — same as –format table –detail full).
- Default:
'json'- Options:
json | table | detailed
- --output <PATH>¶
Write output to PATH instead of stdout.
- --title <SUBSTRING>¶
Filter sessions by title substring (case-insensitive).
- --since <DATE>¶
Only sessions created after DATE (ISO 8601 with timezone).
- --until <DATE>¶
Only sessions created before DATE (ISO 8601 with timezone).
- --workspace <PATH>¶
Only consider sessions from this workspace folder.
- --name <REGEX>¶
Only sessions whose title or ID matches REGEX.
Arguments
- N¶
Required argument
find¶
Find and analyze a session by TITLE (case-insensitive substring match).
If more than one session matches, candidates are printed and the command exits with an error — re-run with id <SESSION_ID> to pick one.
Usage
copilot-session-usage find [OPTIONS] TITLE
Options
- --detail <detail>¶
minimal (identity+total only), compact (+models list, default), or full (+per-model and per-subagent breakdown). Ignored (forced to full) when –format detailed is used.
- Default:
'compact'- Options:
minimal | compact | full
- --format <format_>¶
json (machine-readable), table (human-readable), or detailed (table forced to full detail — same as –format table –detail full).
- Default:
'json'- Options:
json | table | detailed
- --output <PATH>¶
Write output to PATH instead of stdout.
- --workspace <PATH>¶
Only consider sessions from this workspace folder.
Arguments
- TITLE¶
Required argument
id¶
Analyze a session by its exact SESSION_ID (UUID).
Usage
copilot-session-usage id [OPTIONS] SESSION_ID
Options
- --detail <detail>¶
minimal (identity+total only), compact (+models list, default), or full (+per-model and per-subagent breakdown). Ignored (forced to full) when –format detailed is used.
- Default:
'compact'- Options:
minimal | compact | full
- --format <format_>¶
json (machine-readable), table (human-readable), or detailed (table forced to full detail — same as –format table –detail full).
- Default:
'json'- Options:
json | table | detailed
- --output <PATH>¶
Write output to PATH instead of stdout.
- --skill-breakdown¶
Emit a per-skill cost breakdown instead of the default report.
- --tool-breakdown¶
Emit a per-skill/per-subagent tool-call count breakdown.
- --skill <NAME>¶
Filter the report to a single skill (exact or substring match).
Arguments
- SESSION_ID¶
Required argument
latest¶
Analyze the most recently modified session across all workspaces.
Usage
copilot-session-usage latest [OPTIONS]
Options
- --detail <detail>¶
minimal (identity+total only), compact (+models list, default), or full (+per-model and per-subagent breakdown). Ignored (forced to full) when –format detailed is used.
- Default:
'compact'- Options:
minimal | compact | full
- --format <format_>¶
json (machine-readable), table (human-readable), or detailed (table forced to full detail — same as –format table –detail full).
- Default:
'json'- Options:
json | table | detailed
- --output <PATH>¶
Write output to PATH instead of stdout.
- --workspace <PATH>¶
Only consider sessions from this workspace folder.
list¶
List recent sessions with optional cost analysis.
Without –dir, sessions are discovered from workspace storage metadata. With –dir, session directories under PATH are scanned and analyzed.
Usage
copilot-session-usage list [OPTIONS]
Options
- --format <format_>¶
json (machine-readable), table (human-readable), or detailed (table forced to full detail — same as –format table –detail full).
- Default:
'json'- Options:
json | table | detailed
- --output <PATH>¶
Write output to PATH instead of stdout.
- --limit <limit>¶
Max sessions to return.
- Default:
20
- --since <DATE>¶
Only sessions created after DATE (ISO 8601 with timezone).
- --until <DATE>¶
Only sessions created before DATE (ISO 8601 with timezone).
- --workspace <PATH>¶
Only consider sessions from this workspace folder.
- --name <REGEX>¶
Only sessions whose title or ID matches REGEX.
- --title <SUBSTRING>¶
Only sessions whose title contains SUBSTRING (case-insensitive).
- --dir <PATH>¶
List sessions from this debug-logs directory instead of workspace storage.
- --costs¶
Analyze each session and include cost columns (implied by –dir).
pricing¶
Inspect and refresh the runtime GitHub Copilot pricing snapshot.
Usage
copilot-session-usage pricing [OPTIONS] COMMAND [ARGS]...
refresh¶
Refresh the user pricing snapshot from GitHub.
Usage
copilot-session-usage pricing refresh [OPTIONS]
Options
- --force¶
Refresh even if an attempt occurred within 24 hours.
status¶
Show the runtime pricing cache location and refresh metadata.
Usage
copilot-session-usage pricing status [OPTIONS]
refresh-pricing¶
Compatibility alias for pricing refresh.
Usage
copilot-session-usage refresh-pricing [OPTIONS]
Options
- --force¶
Refresh even if an attempt occurred within 24 hours.
skills¶
List skills used across sessions with aggregated cost.
Discovers sessions from workspace storage, analyzes each one, and rolls up per-skill token counts and estimated cost.
Usage
copilot-session-usage skills [OPTIONS]
Options
- --format <format_>¶
json (machine-readable), table (human-readable), or detailed (table forced to full detail — same as –format table –detail full).
- Default:
'json'- Options:
json | table | detailed
- --output <PATH>¶
Write output to PATH instead of stdout.
- --last <DURATION>¶
Only sessions started within the last DURATION (e.g. 7d, 24h, 30m).
- --since <DATE>¶
Only sessions created after DATE (ISO 8601 with timezone).
- --until <DATE>¶
Only sessions created before DATE (ISO 8601 with timezone).
- --workspace <PATH>¶
Only consider sessions from this workspace folder.
Pricing commands¶
Use pricing refresh to explicitly update the user-level pricing snapshot.
The command respects the rolling 24-hour limit unless --force is supplied.
Its output includes the attempt timestamp and, after a successful refresh, the
latest captured pricing timestamp.
Use pricing status to inspect the cache location, timestamps, checksum, and
the most recent refresh error.
The legacy top-level refresh-pricing command remains available as an alias
for pricing refresh.