Skip to content
Statsy
Sign inStart free trial

Command line interface

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

  1. 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.

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

CommandWhat it does
statsy loginSaves an account token. Options: --token, --api-url.
statsy logoutRemoves the saved token.
statsy whoamiShows the workspace, plan, API host and default site.
statsy sites listLists 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 statsHeadline metrics, or a table with --breakdown. Options: --breakdown, --metric, --compare, --limit (10).
statsy timeseriesOne metric over time with a sparkline. Options: --metric (visitors), --granularity (day).
statsy funnels listLists saved funnels.
statsy funnels report <id>Step-by-step report. Option: --window (7d).
statsy visitorsRecent visitors. Options: --query, --limit (20), --live.
statsy goals listLists goals.
statsy goals send <name>Records a server-side conversion. Needs --visitor. Options: --prop, --path.
statsy attributionRevenue by channel. Options: --model (last), --lookback (90).
statsy exportStreams 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.

Last updated · Markdown version