StatsAI docs

CLI reference

Common StatsAI CLI commands for scanning, reporting, source management, subscriptions, and sync.

Last updated: June 9, 2026

This page covers the commands most users reach for after getting started. For the HTTP sync schema and privacy defaults, see the sync contract.

Scanning

Shell

statsai scan --preview
statsai scan
statsai scan --no-cache
statsai scan --replace

Command	What it does
`scan --preview`	Read sources and print normalized totals without writing to SQLite
`scan`	Persist usage events idempotently; skip unchanged JSONL files via signature cache
`scan --no-cache`	Force a full reread without deleting existing data
`scan --replace`	Destructively rebuild a source from scratch

Reporting

Shell

statsai report weekly
statsai report monthly --subscriptions
statsai report all-time
statsai report monthly --json --verbose

Reports group stored usage by provider and account. Add --subscriptions to include per-subscription-period value rows matched by account identity and event date. Use --json --verbose for machine-readable output with token splits and estimated API-equivalent cost.

Source management

Shell

statsai source add --provider codex --path "$HOME/.codex-work"
statsai source disable --source-id src_123
statsai source enable --source-id src_123
statsai source remove --source-id src_123
statsai source remove --source-id src_123 --delete-data
statsai source connect --path "$HOME/.codex-work" --email work@example.com --label work --started-at 2026-05-01
statsai source history --path "$HOME/.codex-work"
statsai source disconnect --path "$HOME/.codex-work" --email work@example.com --ended-at 2026-06-01

Sources identify local log roots. source connect binds a path to a canonical account over a date range. account list is read-only — accounts are created implicitly when you first use --email on a connect or subscription command.

Subscriptions

Shell

statsai subscription add --provider claude --email personal@example.com --plan Pro --price 20 --started-at 2026-05-15 --paid-at 2026-05-15
statsai subscription change --provider codex --email work@example.com --plan Pro --price 200 --started-at 2026-06-01

Subscription periods help the dashboard compare API-equivalent spend against plan value over time. Prices are for analytics, not provider invoicing.

Auth

Shell

statsai auth login
statsai auth status
statsai auth logout

auth login pairs the current machine with your dashboard account. auth status shows the stored device session. auth logout clears local credentials.

Sync

Shell

statsai sync --dry-run
statsai sync --sink file --output ./statsai-sync-batch.json
statsai sync --sink http --since-last
statsai sync --sink http --verify
statsai sync --status
statsai schema sync-batch

Flag / sink	What it does
`--dry-run`	Build the batch and print counts without writing or sending
`--sink file`	Write the full `sync_batch.v1` payload to disk for inspection
`--sink http --since-last`	Send only records after the last successful sync cursor
`--verify`	Check device access and compare local vs remote sync state (HTTP only)
`--status`	Show recorded sync state instead of sending
`schema sync-batch`	Print the JSON Schema the CLI validates before HTTP sync

Auth token precedence for HTTP sync:

Text

--auth-token > STATSAI_SYNC_TOKEN > stored device access token

Imports and background mode

Shell

statsai import summary --path ./reported_usage_summaries.json --dry-run --verbose
statsai daemon --watch
statsai service install
statsai service status

import summary accepts reported or external aggregate evidence when raw local history is incomplete. Imported summaries stay separate from trusted direct adapter events so reports can show gaps without double-counting.

daemon --watch runs a loopback API and rescans when log files change. service install registers a macOS LaunchAgent for persistent collection.