CLI Commands

CLI Commands

The whole tool is one command, prompt-analytics, with a subcommand per analysis. Every analysis command works on the fly — it parses your JSONL in memory (~0.5 s) when there is no fresh extract to read, so you never have to run extract first. extract is just an export (see Architecture).

# zero install, straight from PyPI with uv
uvx --from prompt-analytics-for-claude-code prompt-analytics summary

# or install the command on your PATH
uv tool install prompt-analytics-for-claude-code
prompt-analytics summary

Run prompt-analytics <command> --help for the full flag list of any command.

Global flags

Every analysis command accepts:

Flag	Effect
--output-dir DIR	Where to read/write the extract (default ./output).
--format table|csv|json	table (rich), csv (raw rows on stdout, notes on stderr), or json ({title, rows, notes} with raw numeric values) — pipe into jq, pandas, a notebook.
--pricing PATH	Use a custom pricing grid instead of the bundled one.
--no-cache	Bypass the per-file parse cache.
--from-csv DIR	Analyze the CSVs in DIR as-is — no live parse, no freshness check (e.g. summary --from-csv demo_data). The CLI counterpart of what the dashboard does.
--since YYYY-MM-DD	Only analyze prompts dated on or after this day (inclusive).
--until YYYY-MM-DD	Only analyze prompts dated on or before this day (inclusive), e.g. summary --since 2026-06-01 --until 2026-06-30.

Commands that price tokens also take --provider NAME to choose the rate-card grid for the cost column. NAME is a provider key from the pricing grid — anthropic (default) and copilot ship by default; add your own under providers: (see Accuracy and Pricing).

Totals and breakdowns

Command	Key flags	What it shows
summary		Sessions, prompts, tokens by type, cost per provider, period, subagent share.
by-project	--provider NAME	Cost / tokens / prompts per project, sorted by cost, with each project's share and the running cumulative %.
by-model	--compact --provider NAME	Token and cost split per model (cache writes split by TTL, subagent column); --compact fits 80 columns.
by-token-type	--provider NAME	Cost split per token type — the context-rent share of the bill (cache vs generation vs input).
by-category	--provider NAME	Cost and observed complexity per category (needs categorize first).
timeline	--by day|week|month --provider NAME	Cost / prompts / tokens grouped by calendar period (chronological), each with its share of the total.
prompts	--top N --provider NAME	The N most expensive prompts, with a preview.
sessions	--depth | --top N, --project NAME	Sessions ranked by cost, or --depth for the marginal-cost-by-depth meta-analysis; --project restricts to one.

Cost by content (composition)

The same reconciled bill, attributed across four levels of content — input (category) → output → context → task — plus a transverse before/after mode. Each is metrics-only (no source code is ever stored) and reconciles to the bill by construction. These also power the dashboard Composition page and the dedicated Compare tab (see Dashboard).

Command	Key flags	What it shows
by-output	--provider NAME	Output composition: language mix (by file extension), code vs tests, lines +/− (exact LCS diff), and the prose-vs-code split of generation cost (priced via a local tokenizer).
by-context	--provider NAME	Context composition: what fills the cached, re-read context by source (config / files-read by language / tool output / conversation), splitting one-off loading (cache_write) from rent (cache_read paid every turn it lingers). Totals reconcile to the main-chain cache bill, with an honest (unattributed) bucket.
by-file	--provider NAME	Per-file footprint: edits + line diff (output) crossed with reads + context cost (loading + rent) — the actionable "what to keep out of context".
by-task	--top N --provider NAME	Cost by task (the unit of work, not the prompt): total cost with its context share, prompts, span, dominant category. Tasks come from the real TodoWrite spine, with an inference fallback (time gaps + embeddings + category structure).
impact	--pivot YYYY-MM-DD --provider NAME	Before/after a switch date: workload-normalized ratios (cost/prompt, output cost share, context rent share, cache read/turn, output tokens/prompt) with the workload confounders alongside. Without --pivot, lists detected config-change dates (mtime of CLAUDE.md / settings.json) and exits. An observational split, not a controlled experiment.

by-output / by-context / by-file / by-task need an extract (or live parse) that includes the composition tables; older extracts degrade to an empty table with a "re-run extract" hint. See Architecture for the CSVs.

Power-user analyses (request grain)

Command	Key flags	What it shows
context	--provider NAME	Accumulated context per turn by session depth — the "time to /compact" signal.
ttl	--provider NAME	Cache-TTL expiry losses: what inter-prompt pauses cost in cache re-writes.
compactions	--provider NAME	Each /compact event: context before/after and the cache-rebuild cost.
overhead	--provider NAME	Fixed per-session overhead (system prompt + CLAUDE.md + MCP tools).
model-category	--whatif MODEL --provider NAME	Cost by model × category; --whatif re-prices every cell on another model.
recommend	--min-prompts N --compact-at K	Prescriptive: what compacting long sessions earlier would have saved.
burn-rate	--weeks N --provider NAME	Spend trend: $/day and week over week.
break-even	--provider NAME	Plan break-even: your API-equivalent value vs a Pro/Max subscription.

Pricing, export and pipeline

Command	Key flags	What it shows
compare	--providers A,B	The same usage priced on several grids side by side.
export	--flat --out PATH	Denormalized export for Excel/BI — one row per prompt.
extract	--no-text --since --until --timezone --strict	Write the normalized CSVs to --output-dir.
snapshot		Append current quota utilization to quota_log.csv.
categorize	--semantic --audit-categories --llm --provider --batch --model --limit	Label prompts — heuristic by default; --semantic adds an offline multilingual-embedding pass, --audit-categories is a clustering diagnostic, --llm is the opt-in LLM pass (--provider anthropic|openrouter|ollama|azure). See Prompt Categories.
run	--categorize (+ --llm --provider --batch --model) --no-text --since …	Pipeline: extract (+ optional categorize, full LLM passthrough) + snapshot.
dashboard	--output-dir --no-refresh	Refresh the data (extract + snapshot + local categorize), then launch the Streamlit dashboard — --no-refresh opens the existing CSVs as-is (needs the dashboard extra).
config init		Write a default config.yml into the output directory.

extract and run always regenerate the whole output atomically — there is no incremental mode to misuse, and changing the pricing never requires a re-extract (costs are computed at read time from raw counts).

Common recipes

# Where does the money concentrate, across projects?
prompt-analytics by-project

# How does spend trend month over month? (also: --by day|week)
prompt-analytics timeline --by month

# Zoom in on a single period (any analysis command takes --since/--until)
prompt-analytics summary --since 2026-06-01 --until 2026-06-30

# What does a prompt cost as a session gets deeper?
prompt-analytics sessions --depth

# Label prompts locally, then read the category breakdown
prompt-analytics categorize
prompt-analytics by-category

# Where your cost goes, by content: output, context, per-file, per-task
prompt-analytics by-output
prompt-analytics by-context
prompt-analytics by-file
prompt-analytics by-task --top 20

# Did an optimization help? Split the history on the day you changed something
prompt-analytics impact --pivot 2026-04-01

# Is a Pro/Max plan worth it vs the API?
prompt-analytics break-even

# What would this usage cost billed through GitHub Copilot?
prompt-analytics compare --providers anthropic,copilot

# One flat CSV for Excel / BI
prompt-analytics export --flat --out my_usage.csv

# Full pipeline: extract + categorize + snapshot
prompt-analytics run --categorize

See Dashboard for the UI over the same data, and Accuracy and Pricing for how the numbers are kept honest.