--- title: "Command line tool" description: "Install the revscope command line tool, sign in, add the tracker, connect payments, and query your analytics, from a terminal or an AI agent." url: "https://revscope.co/docs/cli/" --- # 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](https://revscope.co/docs/getting-started.md). The [agents overview](https://revscope.co/AGENTS.md) is the page the agent reads, and this page covers the same commands for people. ## On this page - [Install](#install) - [Create an account or sign in](#sign-in) - [Projects](#projects) - [Add the tracker](#tracker) - [Connect payments](#integrations) - [Query your analytics](#query) - [Commands](#commands) - [Scripts and exit statuses](#scripts) - [Where the credential is kept](#credentials) ## Install On Linux or macOS, this installs the binary into `~/.local/bin`: ```bash 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: ```bash npx revscope --help ``` Use `npx revscope` wherever this page says `revscope`. Run `revscope --help` for every flag a command takes. ## Create an account or sign in ### A new account ```bash 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](https://revscope.co/settings). The free plan covers one website and 10,000 events a month. Paid plans start from [the pricing page](https://revscope.co/pricing.md). ### An existing account ```bash 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: ```bash 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: ```bash 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 ` or set `REVSCOPE_PROJECT`. ## Add the tracker ```bash 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 `` of every page yourself, or have your agent do it. The [tracking script reference](https://revscope.co/docs/tracking-script.md) 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 ```bash 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](https://revscope.co/docs/integrations.md) says how to make a key with the right permissions. ## Query your analytics ```bash 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](https://revscope.co/docs/ai.md). ## Commands | Command | What it does | | --------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `signup` | Creates a free account and its first project, and signs in. | | `login` | Signs in through a browser, or with `--email` and a password. | | `logout` | Ends the credential on the server and forgets it here. | | `whoami` | Shows the signed-in user and their projects. | | `password-reset` | Emails a link for setting the account's password. | | `projects list`, `create` | Lists the projects, or adds one. | | `settings show`, `set` | The time zone, payment success path, and custom domain (Starter plans and up). | | `install snippet` | Prints the tracker snippet for this project. | | `install verify` | Checks a page for the tracker, and for a visit in the last hour. | | `install status` | Recent events, including those not saved yet, and how syncs went. | | `integrations types` | Lists the integrations and the keys each takes. Needs no sign-in. | | `integrations list` | Shows connected integrations and how their syncs went. | | `integrations connect ` | Connects one, or changes its keys. | | `integrations disconnect ` | Removes its keys. Data already synced stays. | | `ga-import connect`, `oauth-url` | Connects a Google credential for importing. | | `ga-import list`, `start`, `cancel`, `delete` | Imports history from [Google Analytics](https://revscope.co/docs/integrations/google-analytics.md). | | `query` | Runs one read-only SQL statement. | | `tables` | Lists the analytics tables. | | `schema` | Prints the schema, or one table's with `--table`. | ## 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: ```json { "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`: | Exit status | Meaning | | ----------- | ----------------------------------------------------------------------------- | | 0 | Success | | 1 | Failure with no more specific status | | 2 | Bad command line or input | | 3 | Not signed in, or the credential was refused | | 4 | Not allowed, such as a plan limit | | 5 | Not found | | 6 | Conflict, such as an account for this website already existing | | 7 | The command ran, and its answer is no, such as a verify that found no tracker | | 75 | Try again later: rate limited, the server is busy, or it could not be reached | ## 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](https://revscope.co/docs/self-hosting.md) server, point the CLI at it with `--api-url` or `REVSCOPE_API_URL`: ```bash 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](https://github.com/eloff/revscope/blob/main/cli/README.md) are on GitHub.