CLI
Read analytics and manage supported resources from a terminal, script or cron job. One small command with no dependencies, speaking the same API as the dashboard and the MCP server.
1. Sign in
npx datastated loginThe CLI shows a short code and opens your browser to approve it while you are signed in. The key it receives is saved under ~/.datastated, readable only by you; nothing secret is ever typed at the prompt. datastated whoami says who this terminal is, and datastated logout forgets the key.
Prefer to manage the key yourself, for CI or a server? Create one on your account page and pass it as DATASTATED_API_KEY or --key dsk_...; either wins over the saved login. DATASTATED_URL points the CLI at a self-hosted instance and DATASTATED_HOME moves the saved key. Install it once with npm install -g datastated and drop the npx.
2. The shape of a command
datastated <resource> [action] <site> [...] [--json] [--yes]
npx datastated window acme.com --from 2026-08-01 --to 2026-08-31
npx datastated breakdown acme.com sources --filter country=US --filter device.not=mobile
npx datastated funnels delete acme.com fun_123 --yes--json: the API's own response, untouched, on every resource command (login,whoamiandlogoutprint for people). Without it you get a readable table.--fromand--to, yyyy-mm-dd, on anything dated; the default is the trailing 30 days.--limit Nand--cursor Cpage through lists; the next cursor is printed when there is more.--filter key=value, repeatable, in the dashboard's own grammar:channel=meta,country=US,page.contains=pricing, with.not,.contains,.not_contains,.starts_with,.ends_withand.matches.--yes: deleting, revoking, removing, disconnecting and regenerating ask first;--yesskips the question, and a script without a terminal must pass it or the command refuses.
Command reference
| Command | What it does |
|---|---|
login / whoami / logout | Connect this terminal through the browser; see who it is; forget the key. |
sites | The sites your key can read. |
sites create <domain> [--name X] | Add a site; you become its owner. |
window <site> | The 30-day analytics window: visitors, pageviews, orders, revenue, top sources. |
claims <site> | Platform claims beside orders attributed to its paid channel, with the platform-level gap. A row marked sample is a labeled example, never your money. |
crawls <site> | Which search engines and AI assistants read your site, from requests your own server reported through @datastated/crawl: hits by purpose (AI answers, search indexing, AI training, other), top crawlers, how many came from the provider's published addresses, and fetches of llms.txt, robots.txt and sitemaps. --json adds paths and per-day counts. |
search <site> | Google Search Console: top search terms and landing pages with Google's own clicks, impressions, CTR and position, and your own orders and revenue beside each page (never Google's, and never attributed to a term). Says so when no property is connected. |
live <site> | Visitors in the last five minutes. |
metrics <site> | Spend, platform-claimed revenue, ledger revenue and MER over the range. |
breakdown <site> <kind> | One table: sources, campaigns, terms, contents, pages, entry-pages, countries, regions, cities, devices, browsers, os, goals, outbound, referrers. |
timeseries <site> [--grain hour|day|week] | Visitors, pageviews, orders and revenue per bucket. |
visitors <site> [--customers] | People in the range; --customers keeps only those who bought. |
visitors get <site> <id> | One person's timeline. |
segments <site> | Saved filters. segments save <site> --name X --filter ... and segments delete <site> <id>. |
funnels <site> | Funnels. funnels results <site> <id>, funnels save <site> --name X --steps '[{"kind":"page","value":"/pricing"},{"kind":"goal","value":"signup"}]', funnels delete <site> <id>. |
alerts <site> | Email alert rules. alerts add <site> --kind goal --goal signup [--to a@b.com,c@d.com], alerts add <site> --kind traffic_spike --threshold 50, alerts on|off <site> <id>, alerts delete <site> <id>. |
annotations <site> | Notes pinned to chart days. annotations add <site> --date 2026-09-01 --text "...", annotations delete <site> <id>. |
digest <site> | The weekly summary. digest set <site> [--on|--off] [--timezone Europe/Paris] [--recipients a@b.com,c@d.com]. |
public <site> | The public traffic page. public on|off|regenerate <site>, public set <site> [--show-revenue on|off] [--indexable on|off]. |
settings <site> | Exclusions, primary goal, renewal revenue, proxy host. settings set <site> [--goal signup] [--renewals on|off] [--proxy stats.yourstore.com] [--exclude-paths /admin,/preview] [--exclude-ips 1.2.3.4]. |
integrations <site> | What is connected (Meta, Google Ads, TikTok, Stripe, GitHub, Shopify) and its last sync. integrations disconnect <site> <kind>. Connecting happens in the dashboard. |
sync <site> [kind] | Pull now. With stripe or github, only that one. With an ad platform (meta, google-ads, tiktok) the ad sync runs for every connected platform and the answer reports that platform's rows. Without a kind, the whole pipeline. |
team <site> | Who has access and pending invites. team invite <site> --email a@b.com --role viewer|owner, team role <site> <user-id> --role owner, team remove <site> <user-id>. |
keys | Your API keys (never their values). keys create --name X [--scope analytics:read --scope funnels:*] [--site yourstore.com] shows the new key once; keys revoke <key-id>. |
DATASTATED_API_KEY | A key to use instead of the saved login. |
DATASTATED_URL | Point the CLI at a different instance (self-host). Defaults to https://app.datastated.com. |
DATASTATED_HOME | Where the saved key lives. Defaults to ~/.datastated. |
Scripting
# last month's revenue, into anything you like
npx datastated window acme.com --json | jq .totals.revenue
# compare Meta's claim with attributed orders
npx datastated claims acme.com --json | jq .totals.gap.revenue
# which AI assistants fetched the docs this week
npx datastated crawls acme.com --from 2026-09-01 --json | jq '.agents[] | {label, hits, verified}'
# a key for a build server that can only read
npx datastated keys create --name ci --scope analytics:read --site acme.comWhen something is refused
A key the API does not accept is reported with the fix: run datastated login, or set DATASTATED_API_KEY to a key from your account page. A key missing a permission is told which one to make a key with. A rate-limited call says how many seconds to wait. Anything else prints the API's own sentence.
Questions? Email us at hello@datastated.com.