Command line tool

The revscope command line tool does from a terminal what the dashboard and settings do in a browser: create an account, add the tracker to a site, connect a payment provider, and query your analytics with SQL. It talks to the same API the dashboard uses, so anything it changes shows up there.

It was built for coding agents such as Claude Code, Codex, and Cursor, which can run every command without a person at the keyboard. To have an agent set RevScope up for you, follow the agent steps in Getting started. The agents overview is the page the agent reads, and this page covers the same commands for people.

Install

On Linux or macOS, this installs the binary into ~/.local/bin:

curl -fsSL https://github.com/eloff/revscope/releases/latest/download/install.sh | sh

Set REVSCOPE_INSTALL_DIR to install it somewhere else. With Node 18 or newer, on Linux, macOS, or 64-bit Windows, you can run it through npm instead, which downloads the native binary the first time and checks it against the release's checksum:

npx revscope --help

Use npx revscope wherever this page says revscope. Run revscope <command> --help for every flag a command takes.

Create an account or sign in

A new account

revscope signup --name "Dana Example" --email dana@example.com \
  --website https://shop.example.com --timezone Europe/Berlin

This creates a free account and its first project, and signs the CLI in. It needs no browser, password, payment details, or email confirmation, which is what lets an agent do it alone. Because nothing confirms the email address, use the real one: it's how the account's owner claims the account later. --timezone sets the time zone the dashboards use and defaults to UTC.

The project is named after the website's host, so shop.example.com becomes shopexamplecom. That name is the path the tracker sends events to, so no two projects can share one. If it's taken, the command exits with status 6 and says so, and --project-name picks another. It also exits 6 when the website or email already has an account, and then the owner should sign in instead. A name needs at least 3 characters, all lowercase letters, digits, or underscores, and demo is reserved.

An account made this way has no password, so only the CLI can reach it. To open the dashboard, run revscope password-reset --email dana@example.com and follow the emailed link to set one. Setting a password signs out every session, the CLI's included, so run revscope login afterwards. MCP and query tokens made before then keep working until they're revoked, so if someone else made the account for you, review those and the account's users in Settings.

The free plan covers one website and 10,000 events a month. Paid plans start from the pricing page.

An existing account

revscope login

This opens your browser on a RevScope page that asks you to approve the CLI. Sign in there, with a password, Google, or Apple, and approve it. The browser then hands the approval back to the command, which is waiting on a port of this computer. That's why the browser has to run on the same machine, and why the command keeps running until you approve, for up to 5 minutes. If no browser opens, the command prints the link on stderr for you to open, and --no-browser skips trying.

On a machine with no browser, such as a server you reach over SSH, sign in with a password instead:

printf '%s\n' "$PASSWORD" | revscope login --email dana@example.com --password-stdin

Or set REVSCOPE_TOKEN to the token from a machine that is already signed in. revscope whoami shows which account the CLI is signed in to, and its projects.

signup and login both refuse to run while a credential is stored or REVSCOPE_TOKEN is set, because replacing a token could lose the only way into an account that has no password. To use a second account, set REVSCOPE_CONFIG_DIR to a different directory, on that command and every later one. Avoid revscope logout unless you mean it: it ends the token on the server for good.

Projects

A project is one website's analytics. revscope projects list lists the account's projects, and revscope projects create adds one:

revscope projects create --website https://blog.example.com --project-name example_blog

RevScope keeps only the project's name, not the website, so --website serves to derive the name, and --project-name replaces that name when it's given. The flag needs version 0.3.0 or later of the CLI, which revscope --version shows, and of the server. revscope.co is up to date, but an older self-hosted server ignores the flag and names the project after the website, and the CLI then prints a warning. The free and Starter plans hold one website, so on them this exits with status 4.

Commands that work on a project use the account's only project when it has one. With several, pass --project <name> or set REVSCOPE_PROJECT.

Add the tracker

revscope install snippet
revscope install verify --url https://shop.example.com/

install snippet prints the script tag for this project. The CLI doesn't edit your site, so add the snippet to the <head> of every page yourself, or have your agent do it. The tracking script reference covers its options.

Once the change is deployed, install verify fetches the page and checks for the tracker. It succeeds when the tracker is in the page's HTML, or when a visit has arrived in the last hour, and exits with status 7 when it finds neither. --require-visit insists on a real visit, and --wait says how long to wait for one. install status shows recent events and how the integrations' syncs went.

Connect payments

revscope integrations types
printf '%s' "$STRIPE_KEY" | revscope integrations connect stripe --secret-key -

integrations types lists each provider and the keys it takes. Passing - as a key's value reads it from stdin, which keeps the key out of your shell history and the process list. Only one value on a command can come from stdin, so Search Console's --service-account-file takes a whole Google key file instead.

Keys are saved without being tried, and payments sync on a schedule. --wait 300 waits up to 5 minutes for the first sync with the new key and reports how it went. Each provider's page under Integrations says how to make a key with the right permissions.

Query your analytics

revscope tables
revscope schema --table pageviews
revscope query "SELECT p.path, COUNT(*) AS views
  FROM pageviews v JOIN paths p ON p.id = v.path_id
  GROUP BY p.path ORDER BY views DESC" --limit 20

Each project's analytics live in a SQLite database, and query runs one read-only SQL statement against it. Read the schema first: tables lists the tables, and schema describes them. Money columns hold integer thousandths of the currency unit, so divide by 1000 for dollars or euros.

A query returns 100 rows unless --limit asks for more, up to 500. Add an ORDER BY and use --offset to page through the rest, or --all to fetch every page. Offsets stop at 5000, so narrow a larger result with WHERE.

The server writes new events to the database every five minutes, so the newest ones can take that long to show up in a query. To read your analytics from Claude, ChatGPT, or another MCP client instead of a terminal, use the MCP server.

Commands

Scripts and exit statuses

Add --json to any command to get its result as JSON on stdout. Failures come out as JSON too, so a script can read why a command failed:

{
  "error": {
    "code": "forbidden",
    "exit_code": 4,
    "message": "Your plan includes one website. Upgrade to Growth to add more.",
    "status": 403
  }
}

Errors that say when to try again include retry_after_seconds. The exit status says what kind of failure it was, the same way with or without --json:

Where the credential is kept

Signing in saves a token that lasts a year to ~/.config/revscope/credentials.json, or under $XDG_CONFIG_HOME when that is set. On Windows without HOME set, it goes in %APPDATA%\revscope. On Linux and macOS, only your user can read the file. The token can do everything you can do in the dashboard, limited by your role on the account. revscope logout ends it, and so does changing your password.

REVSCOPE_CONFIG_DIR moves the file, and REVSCOPE_TOKEN overrides it. To use a self-hosted server, point the CLI at it with --api-url or REVSCOPE_API_URL:

REVSCOPE_API_URL=http://localhost:4320 revscope whoami

The CLI refuses plain http:// except to this machine, so a token never crosses the network unencrypted. Accounts on a self-hosted server need a password, since a reset link needs outgoing email, so signup there takes --password-stdin. Only an instance's first user can sign up, and later users join by invitation. The source and the full README are on GitHub.