Commands

Every command statable accepts, 23 of them, with the flags each one takes. The flags that work everywhere are under statable.

This page is generated from the command tree of the binary, so it says what the tool actually accepts rather than what somebody remembered to write down. It describes v0.2.2; statable version tells you which one you have.

Run any of these with --help for the same text in your terminal, or read man statable-top and friends, which ship in the release archive.

Every command

Command	What it does
statable	Statable analytics from the command line
statable api	Call any endpoint directly
statable api call	Send one request and print the response
statable api describe	Show what one endpoint takes
statable api search	Find the endpoints that mention a word
statable auth	Manage the API key
statable auth login	Store an API key
statable auth logout	Remove the stored key
statable auth status	Show which key is in use and where it came from
statable check	Assert a metric is within bounds, for CI
statable funnel	Run one saved funnel
statable funnels	Saved funnel definitions
statable goals	The conversion goals defined on a site
statable now	How many visitors are active right now
statable props	Custom property keys a site records
statable query	Any query the API can answer
statable series	One metric over time, bucket by bucket
statable sites	List the sites this key can read
statable sites use	Remember a site as the default
statable snippet	The install tag for a site
statable stats	Headline numbers for a period
statable subscription	The plan state of the key's owner
statable top	The leading values of one dimension
statable version	Print the version

statable

Statable analytics from the command line.

statable [flags]

Read your Statable analytics over HTTP, from a terminal, a script, or CI.

Every command prints and exits. Add --json to any of them for machine-readable output on stdout; notes and warnings always go to stderr, so a pipeline stays clean.

Subcommand	What it does
statable api	Call any endpoint directly
statable auth	Manage the API key
statable check	Assert a metric is within bounds, for CI
statable funnel	Run one saved funnel
statable funnels	Saved funnel definitions
statable goals	The conversion goals defined on a site
statable now	How many visitors are active right now
statable props	Custom property keys a site records
statable query	Any query the API can answer
statable series	One metric over time, bucket by bucket
statable sites	List the sites this key can read
statable snippet	The install tag for a site
statable stats	Headline numbers for a period
statable subscription	The plan state of the key's owner
statable top	The leading values of one dimension
statable version	Print the version

Flags

Flag	Meaning
--format string	output format: human, json or csv
--json	shorthand for --format json
--key string	API key to use for this invocation
--no-color	disable colour (NO_COLOR is honoured too)
--no-input	never prompt; fail instead
-q, --quiet	suppress informational notes on stderr
--site string	site id or domain
-v, --verbose	show request ids and underlying causes

statable api

Call any endpoint directly.

statable api [flags]

The escape hatch. Every endpoint is reachable here, including ones the shorter commands do not wrap, and the response is passed through exactly as the server sent it.

api search and api describe read the API's own OpenAPI document, so this command can teach its own surface rather than requiring a second window with the reference open.

Subcommand	What it does
statable api call	Send one request and print the response
statable api describe	Show what one endpoint takes
statable api search	Find the endpoints that mention a word

Plus the global flags.

statable api call

Send one request and print the response.

statable api call <METHOD> <path> [flags]

Send one request to the API.

--var values are parsed as JSON, so --var limit=25 sends a number and --var metrics='["visitors"]' sends an array. --raw-var always sends a string, which is how you send the literal text "25". Guessing between the two is exactly the ambiguity these two flags exist to remove.

Examples:

statable api call GET /sites
statable api call POST /query --var site_id=123 --var metrics='["visitors"]' --var date_range=7d
statable api call GET /current-visitors --var site_id=123

Flags

Flag	Meaning
--allow-errors	print the response body and keep going when the server answers 4xx or 5xx
--body string	request body as JSON, or @file, or - for stdin
-H, --header stringArray	extra request header, as Name: value
--raw-var stringArray	key=value, always sent as a string
--var stringArray	key=value, parsed as JSON when it looks like JSON

Plus the global flags.

statable api describe

Show what one endpoint takes.

statable api describe <path> [flags]

Describe one endpoint: its parameters and the fields of its request body, with the required ones first.

The path may be given with or without a method and with or without the leading slash: /query, query and POST /query all work.

Flags

Flag	Meaning
--refresh	fetch the API description again instead of using the cached copy

Plus the global flags.

statable api search

Find the endpoints that mention a word.

statable api search [term] [flags]

Search the API's own description.

With no term it lists everything, which makes it a table of contents. The document is cached for a day, so repeated searches cost nothing.

Flags

Flag	Meaning
--refresh	fetch the API description again instead of using the cached copy

Plus the global flags.

statable auth

Manage the API key.

statable auth [flags]

Subcommand	What it does
statable auth login	Store an API key
statable auth logout	Remove the stored key
statable auth status	Show which key is in use and where it came from

Flags

Flag	Meaning
--insecure-storage	store the key in a plaintext file instead of the system keyring

Plus the global flags.

statable auth login

Store an API key.

statable auth login [flags]

Store a Statable API key.

With --key the key is taken from the flag. Without it, and on a terminal, you are prompted. Anywhere else — a pipe, CI, an agent — the command prints what to do next and exits rather than blocking on input nobody can type.

Flags

Flag	Meaning
--non-interactive	print what to do next as JSON and exit instead of prompting

Plus the global flags.

statable auth logout

Remove the stored key.

statable auth logout [flags]

Plus the global flags.

statable auth status

Show which key is in use and where it came from.

statable auth status [flags]

Plus the global flags.

statable check

Assert a metric is within bounds, for CI.

statable check [flags]

Read one metric and compare it against a bound.

The exit code is the answer: 0 when the metric is within bounds, 3 when it is not, and the usual 1 or 2 when the check could not be run at all. That third code is the point: a pipeline can tell "traffic dropped" apart from "the tool is broken", which one shared failure code makes impossible.

Examples:

statable check --metric visitors --range 7d --min 100
statable check --metric bounce_rate --max 60
statable check --metric visitors --min 10 --filter page~/pricing

Flags

Flag	Meaning
-f, --filter stringArray	narrow the query, e.g. country=US or page~/blog; repeat to combine with AND
--max float64	fail when the metric is above this
-m, --metric string	the metric to check (default visitors)
--min float64	fail when the metric is below this
-r, --range string	7d, 30d, month, realtime, Nd, or 2026-06-01..2026-06-30 (default 7d)

Plus the global flags.

statable funnel

Run one saved funnel.

statable funnel <id> [flags]

Run a saved funnel over a period and print each step.

Two things to read correctly. The conversion rate is cumulative: it is measured against everyone who entered, not against the step before. Dropoff is the opposite and counts against the previous step alone.

The period decides which sessions are examined. It does not change how long a visitor has to finish, which is one day, always.

Filters here accept session fields only, such as country, browser, device, source or entry page. Event-level fields are rejected, because the funnel's own steps already decide which events count.

Examples:

statable funnel 45
statable funnel 45 --range 7d --filter country=DE

Flags

Flag	Meaning
-f, --filter stringArray	narrow the query, e.g. country=US or page~/blog; repeat to combine with AND
-r, --range string	7d, 30d, month, realtime, Nd, or 2026-06-01..2026-06-30 (default 30d)

Plus the global flags.

statable funnels

Saved funnel definitions.

statable funnels [flags]

The funnels saved on this site.

Definitions are built in the dashboard under Custom Analytics; the API only runs them. Take an id from here into statable funnel <id>.

Examples:

statable funnels
statable funnels --json | jq '.[].id'

Plus the global flags.

statable goals

The conversion goals defined on a site.

statable goals [flags]

The goals a site has defined, and what each one matches.

A goal is a page, a custom event, or a scroll depth. Which of those it is decides which field carries the target, so the kind is shown beside it rather than left to be inferred from an empty column.

This lists the definitions. For how they performed, ask for the breakdown instead:

statable top goals --range 30d

Examples:

statable goals
statable goals --json | jq -r '.[] | select(.kind == "event") | .target'

Plus the global flags.

statable now

How many visitors are active right now.

statable now [flags]

Unique visitors active in the last five minutes.

One number, so it fits a status bar or a shell prompt. For a live series instead of a single figure, use statable series --range realtime --by minute: the realtime window is the only one that buckets by minute, and the only bucket it accepts.

Plus the global flags.

statable props

Custom property keys a site records.

statable props [flags]

The custom properties a site has actually recorded.

This is discovery for the event:props: breakdown, which otherwise needs the key known in advance. Every entry is a key and an event, because a property belongs to the event it was sent with: the same key under two events is two entries. Take both into the next query, the event as a filter and the key as the dimension.

Examples:

statable props
statable props --range 7d
statable top event:props:plan --filter 'event=Signup'

Flags

Flag	Meaning
-r, --range string	7d, 30d, month, realtime, Nd, or 2026-06-01..2026-06-30 (default 30d)

Plus the global flags.

statable query

Any query the API can answer.

statable query [flags]

The full surface of POST /query, for the questions the shorter commands do not cover.

The shape of the answer follows the dimension: none gives totals, a time bucket gives a series, anything else gives a ranked breakdown.

Examples:

statable query --metric visitors,pageviews --range 7d
statable query --metric visitors --dimension time:day --filter country=US
statable query --metric visitors --dimension visit:utm_campaign --limit 25
statable query --metric visitors --dimension event:props:plan --filter event=Signup

Flags

Flag	Meaning
--compare string	previous_period, or an explicit 2026-05-01..2026-05-31 of the same length as --range
-d, --dimension string	one dimension: a time bucket such as time:day, or a breakdown such as event:page
-f, --filter stringArray	narrow the query, e.g. country=US or page~/blog; repeat to combine with AND
-n, --limit int	how many rows (default 10)
-m, --metric stringSlice	metrics to read (default [visitors])
--offset int	skip this many rows
-r, --range string	7d, 30d, month, realtime, Nd, or 2026-06-01..2026-06-30 (default 7d)

Plus the global flags.

statable series

One metric over time, bucket by bucket.

statable series [flags]

One metric over time.

A terminal also gets a sparkline. The scale starts at zero, so a flat week looks flat instead of dramatic.

Flags

Flag	Meaning
--by string	bucket: minute, hour, day, week or month (default day)
--compare string	previous_period, or an explicit 2026-05-01..2026-05-31 of the same length as --range
-f, --filter stringArray	narrow the query, e.g. country=US or page~/blog; repeat to combine with AND
--marker string	sparkline glyphs: blocks, braille or ascii (default blocks)
-m, --metric stringSlice	metrics to read (default [visitors])
-r, --range string	7d, 30d, month, realtime, Nd, or 2026-06-01..2026-06-30 (default 30d)

Plus the global flags.

statable sites

List the sites this key can read.

statable sites [flags]

Subcommand	What it does
statable sites use	Remember a site as the default

Plus the global flags.

statable sites use

Remember a site as the default.

statable sites use <site> [flags]

Remember a site as the default for later commands.

The site may be named by id, by name, or by hostname. A --site flag or a project file still wins over this, so a repository can pin its own site without disturbing the one you chose here.

Plus the global flags.

statable snippet

The install tag for a site.

statable snippet [flags]

The script tag to put on a page.

With no --type this is the tracker. The widget builds draw something and, on a hobby site, count as well -- there the widget is the tracker, so do not install both.

Human output is the tag alone, so it pipes straight into a clipboard or a file. The machine formats carry the script URL and the site id beside it.

Examples:

statable snippet
statable snippet | pbcopy
statable snippet --type globe
statable snippet --json | jq -r .script_url

Flags

Flag	Meaning
--type string	widget build instead of the tracker: globe, live-users, map, countries

Plus the global flags.

statable stats

Headline numbers for a period.

statable stats [flags]

The totals for one period, in one line each.

Four metrics by default: visitors, pageviews, bounce rate and average visit duration. --metric replaces that list rather than adding to it.

--compare adds the previous period's figure and the percent change. The comparison window has to cover the same number of days as the range, so previous_period is the form to reach for unless you mean a specific one.

Examples:

statable stats
statable stats --range 30d --compare previous_period
statable stats -m visitors,visits --filter country=DE
statable stats --range 2026-05-01..2026-05-31 --compare 2026-04-01..2026-04-30
statable stats --json | jq .visitors

Flags

Flag	Meaning
--compare string	previous_period, or an explicit 2026-05-01..2026-05-31 of the same length as --range
-f, --filter stringArray	narrow the query, e.g. country=US or page~/blog; repeat to combine with AND
-m, --metric stringSlice	metrics to read (default [visitors,pageviews,bounce_rate,visit_duration])
-r, --range string	7d, 30d, month, realtime, Nd, or 2026-06-01..2026-06-30 (default 7d)

Plus the global flags.

statable subscription

The plan state of the key's owner.

statable subscription [flags]

The subscription state of whoever owns the key.

It takes no site: the answer is about the account. An account holding only hobby sites has no subscription and answers status "none" with only_hobby true, which means the free plan, not a missing account.

Plus the global flags.

statable top

The leading values of one dimension.

statable top <what> [flags]

Rank one dimension over a period.

is a short name such as pages, sources or countries, or a full dimension such as visit:utm_campaign. Run statable top with no argument to see the short names.

Two dimensions return no comparison at all, whatever --compare says: codes (event:status_code) and goals (event:goal). The rows come back without previous figures rather than with zeroes.

Examples:

statable top pages
statable top sources --range 30d -n 20
statable top countries --compare previous_period
statable top pages --filter 'page~/blog' --format csv

Flags

Flag	Meaning
--compare string	previous_period, or an explicit 2026-05-01..2026-05-31 of the same length as --range
-f, --filter stringArray	narrow the query, e.g. country=US or page~/blog; repeat to combine with AND
-n, --limit int	how many rows (default 10)
-m, --metric stringSlice	metrics to read
--offset int	skip this many rows
-r, --range string	7d, 30d, month, realtime, Nd, or 2026-06-01..2026-06-30 (default 7d)

Plus the global flags.

statable version

Print the version.

statable version [flags]

Print the version, and enough about the build to act on a bug report.

A release carries its tag. A binary from go install carries the module version Go recorded, and one built from a clone carries its commit — so there is always something to name, rather than the word "dev" forever.

Plus the global flags.

---

Ready to take control of your web analytics? Try Statable free for 30 days. No credit card required, full feature access, built for GDPR. Start your free trial or view a live demo.