tokenstat
homepricingstatshelpsign in
tokenstat
Reading your usage

Which tokenstat command shows what

György
Reviewed by
György
Updated Aug 3, 2026 3 min

There is only one thing that reads your logs, and it is tokenstat scan. It writes counters into a local archive. Every other command is a view over that archive, which is why they are all fast and why none of them touch the network.

That split is worth holding onto, because it explains the whole command list. You are not choosing between tools. You are choosing a shape to look at the same data in.

tokenstat scan       # read the logs into the archive
tokenstat            # look at it

Start with the bare command

Typed on a terminal with nothing piped, tokenstat opens a full-screen client: tabs, headline numbers, and a command field. If the archive was last scanned more than 10 minutes ago it rescans on open, so you are not reading yesterday's picture by accident.

Pipe it, or run it in a script, and it prints a one-shot report instead. tokenstat summary is that same report on demand.

Pick the shape of the question

You want to know Command
The headline: totals, activity grid, models tokenstat summary
When you work, as a calendar tokenstat heatmap
Whether it was a heavy Tuesday tokenstat daily
The trend over weeks or months tokenstat weekly / tokenstat monthly
Which model is actually doing the work tokenstat models
Which repository is absorbing it tokenstat projects
One conversation at a time tokenstat sessions
Load inside a five-hour window tokenstat blocks
The year, told as a story tokenstat wrapped
Whether the archive itself is healthy tokenstat doctor

blocks is the one people skip and then find useful. Several vendors meter on rolling multi-hour windows rather than calendar days, so a five-hour view shows a burst that a daily total flattens out.

Four filters, every command

Every view takes the same filters, which means you learn them once:

tokenstat models --since 2026-07-01
tokenstat daily --last 14
tokenstat projects --model claude-opus-4-6
tokenstat sessions --project tokenstat
  • --since and --until bound a date range
  • --last N is the last N periods of whatever the command counts in
  • --model narrows to one model
  • --project narrows to one repository

They compose. tokenstat daily --last 30 --model claude-opus-4-6 is a month of one model, by day.

Everything speaks JSON

Add --json to any command and you get the machine-readable version of the same report:

tokenstat models --json

This is the piece that makes tokenstat scriptable rather than just readable. It is also how the website profile gets a heatmap: tokenstat heatmap has a stable JSON contract, not a redrawn picture.

For a full dump rather than a report, tokenstat export writes every event as CSV or JSON. And tokenstat mcp runs an MCP server over stdio, so a coding agent can query your own usage the same way you would.

Prices are not in the binary

List rates ship as a snapshot you fetch, not as numbers baked into the release:

tokenstat pricing --refresh

Run that once. Without it, token counts still work everywhere, but the money columns have nothing to price against. tokenstat pricing on its own shows what snapshot you currently hold.