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 with readable metric names and included limits.
• models: Show models returned by the live Copilot SDK ListModels call, with runtime limits, reasoning support, policy state, and $ I/O token pricing.
• model-docs: Show docs-backed model metadata from github/docs, joined with the live CLI model list. Use --all for broader docs-backed fields, or --visible-only to hide docs rows your account cannot select right now.
• tools: Show available tools.
• usage: Show billing usage report from GitHub API (--billing premium-request|ai-credits|auto), with included limits from quota snapshots. Default table shows Used credits or requests; use --with-pricing to join SDK model token pricing, or -f yaml for billed amounts.
• 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 --wrap-long-text to show full description and summary columns with terminal-width wrapping instead of compact truncation. Use --discover to enable automatic MCP and skill config discovery when commands create temporary sessions (for example .mcp.json and project skill directories). Use --show-hidden --help to include hidden diagnostics commands and hidden flags in help output.

Examples

Quota Information

Shows the current usage and included limits for Copilot quota metrics (for example Premium Interactions or AI Credits when present).

copilot-show quota

Example Output:

--- Quota Information ---
┌──────────────────────┬──────────┬──────┬────────────┬─────────┐
│ METRIC               │ INCLUDED │ 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 (legacy premium requests, github/docs):
- Copilot Pro: 300
- Copilot Pro+: 1,500
- Copilot Business: 300
- Copilot Enterprise: 1,000
- Copilot Max: see github/docs AI credits tables (20,000 total AI credits/month)

Month Progress (UTC): 38.8%
...

List Models

Lists models returned by the local Copilot CLI server through the Copilot SDK ListModels API. The table includes runtime details such as token limits, reasoning support, vision limits, policy State, and $ I/O per-million-token pricing from SDK billing metadata. Use -f yaml for full SDK fields, including cache-read/write prices and docs catalog version metadata.

copilot-show models

# Try the latest github/docs tables for catalog version metadata
copilot-show models --latest

Model Docs

Shows the docs-backed model matrix from github/docs, joined with the live CLI model list. By default it shows docs-backed models that support Copilot CLI, including Visible Now and compact Supported Plans. Use --all for the full docs catalog with summary counts, compact Plans and Modes columns, live State, and sorting that surfaces visible models first. Retired-model history and Live Models Without Docs Snapshot Match appear after the main table. $ I/O comes from live SDK billing metadata when a docs row matches a model in ListModels; otherwise it shows -.

copilot-show model-docs

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

# Default CLI-focused table; hide docs rows not visible in ListModels
copilot-show model-docs --visible-only

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

# Full docs catalog plus live join details
copilot-show model-docs --all -f yaml

Finding models you cannot select right now

There is no separate Copilot SDK flag to list models outside your account entitlement. copilot-show combines two sources instead:

For the broadest static catalog, use copilot-show model-docs --all -f yaml. Runtime billing and capability fields still come only from models returned by ListModels.

List Tools

Lists built-in tools available to Copilot.

copilot-show tools

Use --wrap-long-text when you want the full tool description wrapped in the table instead of a shortened first line:

copilot-show tools --wrap-long-text
copilot-show skills --wrap-long-text

Usage Report

Shows detailed billing usage from the GitHub API (requires gh CLI). By default it auto-detects billing mode (premium-request vs ai-credits) from quota snapshots and API data; use --billing premium-request or --billing ai-credits to force a mode. The default table focuses on Used credits or premium requests grouped by Period and SKU with subtotals and included limits from quota snapshots when available. Billed quantities and USD amounts remain available in YAML output (-f yaml). Use --with-pricing to append a second table that joins each usage row with live Copilot SDK model token pricing ($ I/O per M tokens). Unmatched models show - in the pricing column. With --with-pricing -f yaml, reports also include withPricing, ioSummary, and tokenPricing fields when a model match is found. 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 (auto-detects billing mode)
copilot-show usage

# Join usage with live SDK model token pricing
copilot-show usage --with-pricing

# Full billing fields (including billed quantities and USD amounts)
copilot-show usage -f yaml

# Usage plus joined pricing in YAML
copilot-show usage --with-pricing -f yaml

# Force premium-request billing
copilot-show usage --billing premium-request

# Force AI credits billing (June 2026+ individual plans)
copilot-show usage --billing ai-credits

# 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 PR column means premium requests and preserves fractional multipliers such as 0.33. PR Cost is the hypothetical $0.04-per-PR overage charge; if your usage stays within the premium requests included in your plan, the actual overage billed can still be $0. Use --api-costs to estimate equivalent API cost from shutdown token usage. When shutdown metrics contain cacheReadTokens, the estimate treats them as a subset of inputTokens, prices only the uncached remainder at the full input-token rate, and prices cached reads separately when the selected model has a verified cached-input price. The default table lays out token kinds, token counts, USD/Mtok rates, and cost subtotals as aligned multiline cells within each model row, and its Input Tokens row shows the billed uncached remainder rather than the raw total input. If future shutdown logs add extra token-usage keys such as cacheOutputTokens, the new table will add an extra row for that model automatically; those rows remain unpriced until explicit API-pricing support is added. 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)
• mcp-config: List user-configured MCP servers from Copilot settings
• discover: Unified discovery snapshot from server-scoped SDK APIs (MCP, skills, agents, instructions, and canonical discovery paths)
• account: Show account authentication and registered users
• session-metadata [sessionID]: Show session metadata snapshot (model, mode, workspace)
• session-usage [sessionID]: Show live per-session usage metrics, including AI credits converted from NanoAiu (TotalNanoAiu / 10⁹)
• session-auth [sessionID]: Show per-session authentication status
• 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.
• resume-branches [sessionID]: Trace inferred work branches that start from session.resume
• validate-events [sessionID]: Validate local session events against copilot-sdk generated types

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