Getting started

Before you begin

You need:

• A Mac or Linux machine with local AI tool logs (Claude Code, Codex, Cursor, Copilot, and others)
• A StatsAI account for the hosted dashboard
• Network access for one-time device pairing and optional sync

StatsAI does not require provider API keys. The CLI reads what your tools already log locally.

Install the CLI

On macOS, the fastest path is Homebrew:

brew install starkdmi/tap/statsai

Or use the release installer script:

curl -LsSf https://github.com/starkdmi/statsai/releases/latest/download/statsai-installer.sh | sh

You can also build from source in the open-source repo with cargo install, or download a release archive from GitHub.

Confirm the install:

statsai --version

Pair your first device

Sign in to the dashboard, then authorize your machine from the CLI:

statsai auth login
statsai auth status

auth login opens the web app configured by STATSAI_WEB_URL, completes device pairing through a loopback callback, and stores a device refresh token locally for automatic sync.

Scan local provider logs

Preview what the CLI finds without writing to SQLite:

statsai scan --preview

Persist normalized events:

statsai scan

By default, StatsAI reads configured and discovered local sources for supported providers. Re-running scan refreshes existing rows when adapter metadata improves, so token splits and cost estimates can backfill without duplicating events.

Sync to your dashboard

Check what would be sent without writing anything:

statsai sync --dry-run

To inspect the full JSON batch locally:

statsai sync --sink file --output ./statsai-sync-batch.json

Send sanitized rollups to the hosted API:

statsai sync --sink http --since-last

Check sync state and the last successful batch:

statsai sync --status

Verify device access and compare local vs remote sync state:

statsai sync --sink http --verify

Optional: configure sources and accounts

Most users can start with defaults. When you need explicit control:

statsai source add --provider codex --path "$HOME/.codex-work"
statsai source connect --path "$HOME/.codex-work" --email work@example.com --label work --started-at 2026-05-01
statsai subscription add --provider claude --email personal@example.com --plan Pro --price 20 --started-at 2026-05-15 --paid-at 2026-05-15

Canonical accounts are created implicitly the first time you use --email on a source connection or subscription command. Labels like work or personal are display metadata, not account identity.

Optional: background collection

For continuous local scanning, run the loopback daemon with file watching:

statsai daemon --watch

On macOS you can also install a LaunchAgent so collection survives restarts:

statsai service install
statsai service status

Open the dashboard

After a successful sync, open the hosted dashboard and sign in with the same account you used during device pairing. You should see cross-device rollups, provider breakdowns, and activity views backed by the sanitized summaries you synced.

If nothing appears yet, confirm statsai auth status shows an active device session and re-run statsai sync --sink http --since-last.