CLI and MCP

Which tokenstat command shows what

Reviewed by

Updated Aug 3, 2026 4 min

tokenstat scan collects usage counters and metadata into a local archive. Reports read that archive. Setup, vendor fetches, reference refreshes, updates, account sync, and remote-host commands have separate network behavior.

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.

The tokenstat full-screen client on the Summary tab: sessions, requests, input and output totals, an activity grid coloured by day, and a model table with input, output, cache, total and price columns — The Summary tab. Numbered tabs across the top, the same archive underneath each one.

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`
A heavy Tuesday	`tokenstat daily`
The trend over weeks or months	`tokenstat weekly` / `tokenstat monthly`
Which model handled 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`
Is the archive healthy	`tokenstat doctor`

The Daily tab of the tokenstat client: one row per day, newest first, with input, output, cache, total and value columns, and a bar chart of each day's total — The Daily tab, which is tab 2 in the client and what tokenstat daily prints. Same numbers, two ways in.

The Models tab of the tokenstat client: every model on the machine with input, output, cache, total and value columns, and a bar chart of their relative share — The Models tab, which is tab 5 in the client and what tokenstat models prints. Same numbers, two ways in.

blocks is useful for vendors that meter on rolling multi-hour windows instead of calendar days. A five-hour view shows bursts 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 that 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

The JSON output makes tokenstat scriptable. It also powers the website profile heatmap: tokenstat heatmap has a stable JSON contract.

For a full dump, tokenstat export writes every event as CSV or JSON. tokenstat mcp runs an MCP server over stdio, so a coding agent can query your usage.

Prices are not in the binary

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

tokenstat pricing --refresh

Setup fetches the reference snapshots. Run a refresh to update them. Token counts remain available when prices are missing. tokenstat pricing on its own shows what snapshot you currently hold.

Manage collection and a host

tokenstat setup scans, configures scheduled collection and updates, and offers an optional account step. See install options.

tokenstat host shows the always-on service state. It also provides install, start, stop, logs, and device-access commands. See host setup.

Why cache reads dominate your token count explains what the columns in these reports mean.
Set a budget and put usage in your prompt covers the two commands designed for quick status checks.
What tokenstat counts, and where the numbers come from is the source side of the same story.