CLI Reference

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

analyze

Analyze a single session by its debug-log directory PATH.

PATH is typically the VS Code Copilot session debug log directory — this is the fastest path, no discovery needed.

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.

Arguments

PATH

Required 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.

--since <DATE>

Only sessions created after DATE (YYYY-MM-DD or ISO 8601).

--workspace <PATH>

Only consider sessions from this workspace folder.

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.

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 (metadata only — no cost analysis).

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 (YYYY-MM-DD or ISO 8601).

--workspace <PATH>

Only consider sessions from this workspace folder.