Command line interface

Install the statsy command from npm, sign in with an account token, and print overviews, breakdowns, funnels, visitors and CSV exports.

The statsy command prints the same reports as the dashboard, as borderless tables in a terminal or as JSON in a script. It needs Node.js 20 or newer.

Install and sign in

bash

npm install -g @statsy.co/cli
# or run it once without installing
npx @statsy.co/cli --help

Create an account token
In Site settings › API tokens, create a token with the scope Whole account. It starts with sta_ and is shown only once. Site tokens do not work with the CLI.
Run statsy login
statsy login asks for the token and hides what you type. Pass it directly with --token if you prefer. There is no browser sign-in yet.
bash
```
statsy login
```
The token is written to ~/.statsy/config.json with file permissions 0600. statsy whoami shows the workspace, plan and default site; statsy logout removes the saved token.
Choose a default site
Most commands need a site. Set one once with statsy sites use <site> and leave --site off afterwards.
bash
```
statsy sites list
statsy sites use ws_yoursitekey
```

Tip. In CI, skip statsy login and set STATSY_TOKEN instead. STATSY_API_URL points the CLI at a different API host; it defaults to https://api.statsy.co. Environment variables win over the config file.

Commands

Command	What it does
`statsy login`	Saves an account token. Options: --token, --api-url.
`statsy logout`	Removes the saved token.
`statsy whoami`	Shows the workspace, plan, API host and default site.
`statsy sites list`	Lists sites. Runs by default for a bare statsy sites.
`statsy sites add <domain>`	Adds a site. Options: --name, --timezone.
`statsy sites use <site>`	Sets the default site for later commands.
`statsy stats`	Headline metrics, or a table with --breakdown. Options: --breakdown, --metric, --compare, --limit (10).
`statsy timeseries`	One metric over time with a sparkline. Options: --metric (visitors), --granularity (day).
`statsy funnels list`	Lists saved funnels.
`statsy funnels report <id>`	Step-by-step report. Option: --window (7d).
`statsy visitors`	Recent visitors. Options: --query, --limit (20), --live.
`statsy goals list`	Lists goals.
`statsy goals send <name>`	Records a server-side conversion. Needs --visitor. Options: --prop, --path.
`statsy attribution`	Revenue by channel. Options: --model (last), --lookback (90).
`statsy export`	Streams a full breakdown as CSV to standard output. Options: --dimension (path), --metric, --format csv.

Periods and ranges

--period takes 24h, 7d, 30d, 90d, 12mo or now (the last 30 minutes). Most commands default to 7d; timeseries, funnels report, attribution and export default to 30d. For exact dates use --from and --to with ISO dates instead.

Output and exit codes

--json works on any command and prints pretty JSON. With visitors --live it prints one compact JSON object per line, which is easy to pipe. statsy export always writes CSV and ignores --json. Colour turns itself off when output is not a terminal, or when NO_COLOR is set.

bash

statsy stats --period 30d --breakdown channel --metric revenue
statsy export --dimension path --period 90d > pages.csv
statsy visitors --live

Exit codes make failures easy to branch on: 0 success, 1 a general error, 2 not authenticated, 3 forbidden or a trial that has ended, 4 rate limited.

Frequently asked questions

Is there a command line tool for Statsy analytics?

Yes. The statsy command is published on npm as @statsy.co/cli under the MIT licence. It prints overviews, breakdowns, time series, funnels, live visitors, revenue attribution and CSV exports from any terminal, and every command has a --json flag for scripts.

Which token does the CLI need?

An account token, which starts with sta_ and acts for the whole workspace. Site tokens (st_) are refused. Create one under Site settings, API tokens, and keep it in a secret manager or the STATSY_TOKEN environment variable.

Can I run the Statsy CLI in CI or a cron job?

Yes. Set STATSY_TOKEN in the environment, skip statsy login, and pipe the output. Colour turns itself off when output is not a terminal, exit codes distinguish auth, permission and rate-limit failures, and statsy export streams CSV to standard output.

Does the CLI cost extra?

No. The CLI, the MCP server and the REST API are included on every plan and during the free trial. They read the same data the dashboard shows, under the same permissions.

Last updated 18 September 2026 · Markdown version