Install the tokenstat CLI on macOS, Linux, or Windows

Install the CLI to read usage from a terminal. On macOS, you can also use the desktop app without a separate CLI installation.

macOS and Linux

curl -fsSL https://tokenstat.ai/install.sh | bash

Windows

irm https://tokenstat.ai/install.ps1 | iex

What setup does

The installer downloads the matching release, verifies SHA256SUMS, and puts it in a user-writable directory: ~/.local/bin on macOS/Linux or %LOCALAPPDATA%\tokenstat on Windows. Unix releases include the tokenstat-hostd helper as well as the CLI. Installing the helper does not by itself enable an always-on host.

It then runs tokenstat setup, which:

1. Scans supported local usage records and fetches price and catalog reference data.
2. Installs hourly usage collection and enables scheduled automatic updates by default.
3. Offers an optional account connection when running interactively. Linked devices can sync on their plan's interval.

The Unix installer and Windows installer are available to read before running them.

Open your first report

tokenstat

In an interactive terminal this opens the full-screen report. Use tokenstat summary for a one-shot report or tokenstat models for a model breakdown. If no usage is found, see no sessions found.

Account and schedule options

No account is required for local reports. You can rerun setup and skip its account step:

tokenstat setup --local-only

To skip installing background schedules during a fresh install:

curl -fsSL https://tokenstat.ai/install.sh | bash -s -- --no-schedule

$env:TOKENSTAT_NO_SCHEDULE=1; irm https://tokenstat.ai/install.ps1 | iex

tokenstat setup --local-only --no-schedule skips both setup steps. It does not unlink an existing account or remove schedules already installed. Use tokenstat schedule to inspect scheduling options.

Automatic updates

Automatic daily updates are enabled by default during scheduled setup. To disable them:

tokenstat update --auto off

To check or update manually:

tokenstat update --check
tokenstat update

Updates verify release checksums and run the downloaded binary to check its version and help output before replacing the installed copy. A failed replacement can restore the previous binary. On macOS, an existing signed installation requires a signed replacement.

Keep usage before tools clean up

Hourly scans preserve counters before source logs disappear. Claude Code normally removes transcripts after 30 days. Some totals can be recovered from its rollup, but the original session detail may be lost.

tokenstat doctor reports archive coverage and backup status. Scans make one archive backup per day and retain seven copies. Restoration is manual.

Other installation options

GitHub Releases provide stable CLI downloads. With a Rust toolchain, build from the software repository using cargo install --path crates/tokenstat-cli.

For a machine that should run agents after the app closes or you log out, follow always-on host setup. To remove tokenstat, see uninstall instructions.

Connect an agent through MCP

The CLI includes tokenstat mcp. Follow MCP setup and agent instructions for copyable macOS/Linux configuration, workspace discovery, tasks, notes and the full tool reference.