copilot-show

copilot-show

copilot-show is a command-line tool to inspect various information from the GitHub Copilot CLI, such as quotas, models, and tools. It is built on top of github.com/github/copilot-sdk/go.

Documentation

• docs/research/README.md: curated research notes on premium-request billing, session event-model caveats, and API pricing overrides.

Installation

Install via go install (ensure your GOPATH/bin is in PATH):

go install github.com/apstndb/copilot-show@latest

Or using mise:

mise use -g go:github.com/apstndb/copilot-show@latest

Usage

Run the tool with a subcommand to inspect specific resources.

Available subcommands:

• quota: Show Copilot Premium Interactions usage and entitlement.
• models: Show available models with live runtime details and docs-backed multipliers.
• model-docs: Show CLI-focused model metadata from github/docs, with --all for broader docs-backed fields.
• tools: Show available tools.
• usage: Show billing usage report from GitHub API, with model multipliers and entitlement joined from the models list and quota snapshots.
• stats: Show local usage statistics aggregated from session history, with optional API-equivalent cost estimates from token usage.
• turns: Show turn-by-turn usage statistics for a session.

Common Options

Use --format yaml (or -f yaml) to get detailed raw data in YAML format. Use --table-mode ascii or --table-mode markdown to change the table rendering style. Use --show-hidden --help to include hidden diagnostics commands and hidden flags in help output.

Examples

Quota Information

Shows the current usage and entitlement of Copilot Premium Interactions.

copilot-show quota

Example Output:

--- Quota Information ---
┌──────────────────────┬─────────────┬──────┬────────────┬─────────┐
│ METRIC               │ ENTITLEMENT │ USED │ OVERAGE    │ USAGE % │
├──────────────────────┼─────────────┼──────┼────────────┼─────────┤
│ chat                 │           0 │    0 │ Disallowed │ -       │
│ completions          │           0 │    0 │ Disallowed │ -       │
│ premium_interactions │         300 │   65 │ Disallowed │ 21.7%   │
└──────────────────────┴─────────────┴──────┴────────────┴─────────┘
Last Updated: 2026-03-12T20:41:07+09:00

Plan Reference (Approximate Monthly Entitlement):
- Copilot Free: 50
- Copilot Pro / Business: 300
- Copilot Enterprise: 1,000
- Copilot Pro+: 1,500

Month Progress (UTC): 38.8%
...

List Models

Lists available AI models with live runtime details such as token limits and reasoning support, while preferring the docs-backed paid multiplier table from github/docs for the multiplier column.

copilot-show models

Model Docs

Shows the docs-backed model matrix from github/docs, joined with the live CLI model list. By default it shows the docs-backed models that support Copilot CLI, including Visible Now and Supported Plans so you can compare what your account sees now with what other plans may expose. Use --all when you also want docs rows that do not support Copilot CLI, retired-model history, broader metadata such as Agent/Ask/Edit modes and task areas, and the full multi-client YAML surface. Multiplier prefers the docs-backed paid multiplier table and only falls back to live runtime billing when the docs snapshot has no multiplier for a visible row.

copilot-show model-docs

# Try the latest github/docs tables first
copilot-show model-docs --latest

# Include broader docs-backed metadata
copilot-show model-docs --all

List Tools

Lists built-in tools available to Copilot.

copilot-show tools

Usage Report

Shows detailed billing usage for premium requests from the GitHub API (requires gh CLI). Displays grouped results by Period and SKU with subtotals, multipliers, and entitlement information. Supports relative date/month/year by specifying negative values (e.g., -d -1 for yesterday). Multiple periods can be shown with the --last flag. The Period column can be sorted in ascending or descending order with the --sort-order flag (default is desc).

# Current month (default)
copilot-show usage

# Yesterday's report
copilot-show usage -d -1

# Last 7 days daily report
copilot-show usage -d -1 --last 7

# Last 3 months monthly reports
copilot-show usage -m 0 --last 3

Stats

Aggregates usage statistics from local session history (~/.copilot/session-state/*/events.jsonl). Useful for understanding which models are consuming your quota. The Premium Requests (Cost) column preserves fractional multipliers such as 0.33. Use --api-costs to estimate equivalent API cost from shutdown token usage, including cached token reads when the selected model has a verified cached-input price. Models without matching API pricing still remain in the output; their API-cost cells stay empty and the printed total becomes a lower bound. Model availability is still plan-dependent, so local shutdown metrics can contain model IDs that are not currently visible in copilot-show models. Use --api-pricing <file> to overlay those built-in public prices with local YAML values. This is intended as a safe starting point for local effective-price overrides, without baking private contract terms into the tool. Omitted fields inherit the built-in catalog. If you add a model that is not in the built-in catalog, define at least inputUsdPerMToken and outputUsdPerMToken. Use --api-pricing-template to dump a commented starter file with every built-in model and known value.

copilot-show stats [-a]

# Compare premium-request overage vs. API-equivalent token cost
copilot-show stats --api-costs

# Write a commented starter file you can edit locally
copilot-show stats --api-pricing-template > ~/.copilot/api-pricing.yaml

# Apply local API price overrides (implies --api-costs)
copilot-show stats --api-pricing ~/.copilot/api-pricing.yaml

Example override file:

models:
  gpt-5.4:
    inputUsdPerMToken: 1.50
    outputUsdPerMToken: 12.00
  claude-opus-4.6:
    inputUsdPerMToken: 4.00
    outputUsdPerMToken: 20.00

Turns

Displays turn-by-turn usage statistics for a specific session. The command reconstructs assistant turn windows from local event history and shows:

• chronological Turn #
• Segment numbers that increment on session.start / session.resume
• the raw Copilot Turn ID, which can repeat within one session

copilot-show turns [sessionID]

YAML Output

All commands support -f yaml flag to output detailed data in YAML format.

copilot-show quota -f yaml

Hidden Subcommands

The following commands are hidden by default but can be executed by specifying their names:

• agents: List available Copilot agents
• skills: List available skills (name, source, enabled, path, description)
• extensions: List available extensions (id, status, source, pid)
• plugins: List installed plugins (name, marketplace, version)
• mcp: List configured MCP servers (name, status, source)
• current-model: Show the currently selected model ID
• current-agent: Show the currently selected agent
• mode: Show the current agent mode
• plan: Read the current plan file
• workspace: List files in the workspace
• read-file <path>: Read a specific file from the workspace
• ping: Check connection to the server
• status: Show CLI version and authentication status
• sessions: List all sessions with PID information
• history [sessionID]: Show conversation history (from local event logs). The default --view raw keeps the event-by-event timeline in fixed Time / Delta / Event columns. --view spans pairs tool.execution_start and tool.execution_complete by toolCallId, and --group-by turn folds Assistant Turn Start/End into synthetic turn headers. In this grouped mode, User and Turn are shown at the same structural level under each interaction, while Assistant and Tool rows remain nested under the turn. The table also switches to Time / Span / Structure / Detail so the hierarchy stays visually aligned.
• graph [sessionID]: Show a graph-oriented summary of local event logs, including parentId gaps, direct interactionId hubs, and nested parentToolCallId groupings.

History Event Reference

history reads local ~/.copilot/session-state/<session>/events.jsonl rows and projects them in three ways:

• --view raw: event-by-event timeline in Time / Delta / Event
• --view spans: tool start/end pairs collapsed into Time / Span / Event
• --view spans --group-by turn: turn-aware layout in Time / Span / Structure / Detail

The following event types currently have explicit formatting:

Some rows in the history output are synthetic and do not come directly from a single type value:

License

MIT License