# Command line interface

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

Section: CLI, MCP and API  
Canonical page: https://statsy.co/docs/developers/cli  
Last updated: 2026-09-18

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
```

1. Create an account tokenIn **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.
2. 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.
3. Choose a default siteMost 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.

Previous: [Overview](https://statsy.co/docs/developers)  
Next: [MCP server for AI assistants](https://statsy.co/docs/developers/mcp)