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.

Many commands also take --provider NAME to price on a specific grid (anthropic by default; copilot ships too).

Totals and breakdowns

Command	Key flags	What it shows
summary		Sessions, prompts, tokens by type, cost per provider, period, subagent share.
by-project	--pareto --provider	Cost / tokens / prompts per project, sorted; --pareto adds share + cumulative %.
by-model	--compact --provider	Token and cost split per model (cache writes split by TTL, subagent column); --compact fits 80 columns.
by-token-type	--provider	Cost split per token type — the context-rent share of the bill (cache vs generation vs input).
by-category	--provider	Cost and observed complexity per category (needs categorize first).
prompts	--top N --provider	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.

Power-user analyses (request grain)

Command	Key flags	What it shows
context	--provider	Accumulated context per turn by session depth — the "time to /compact" signal.
ttl	--provider	Cache-TTL expiry losses: what inter-prompt pauses cost in cache re-writes.
compactions	--provider	Each /compact event: context before/after and the cache-rebuild cost.
overhead	--provider	Fixed per-session overhead (system prompt + CLAUDE.md + MCP tools).
model-category	--whatif MODEL --provider	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	Spend trend: $/day and week over week.
break-even	--provider	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	--llm --provider --batch --model --limit	Label prompts — heuristic by default, LLM opt-in.
run	--categorize (+ --llm --provider --batch --model) --no-text --since …	Pipeline: extract (+ optional categorize, full LLM passthrough) + snapshot.
dashboard	--output-dir	Launch the Streamlit dashboard — reads an extract, so run extract first (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 --pareto

# 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

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