# Command line interface

> Install the statsy command, 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-15

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.

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