# RevScope for agents

RevScope is revenue attribution analytics for websites. A small script records what visitors do, and RevScope joins that to the payments they make, to show which pages, channels, and campaigns bring in revenue.

An agent can do all of this from the `revscope` command line tool, with no browser and no human step: create a free account, install the tracker, and query the analytics with SQL.

## Install the CLI

On Linux or macOS:

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

This puts the binary in `~/.local/bin`, or in `$REVSCOPE_INSTALL_DIR`. With Node 18 or newer, on any platform including Windows, run it with no install. It fetches the native binary on first run. Use `npx revscope` wherever a command below says `revscope`.

```sh
npx revscope --help
```

## Create a free account

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

That is the whole signup. It needs no browser, password, payment details, or email confirmation. It creates the account and a first project, then saves a token that lasts a year to `~/.config/revscope/credentials.json`, so later commands are already signed in. `--timezone` is optional and defaults to UTC.

- Use the name and email of the person you are acting for. That address is how they claim the account.
- The free plan covers one website and 10,000 events a month, and keeps 6 months of data. Paid plans go through checkout on [the pricing page](https://revscope.co/pricing.md).
- Exit status 6 is a conflict, and the message says which: an account already exists for this website or email, so ask its owner to sign in, or the project name derived from the website is taken, so choose another with `--project-name`.
- Exit status 75 can follow a signup that succeeded with its answer lost. If a retry then exits 6, the token is gone and `revscope password-reset --email dana@example.com` reaches the account.
- `signup` also exits 6 while a credential is stored or `REVSCOPE_TOKEN` is set, because replacing a token can lose the only way into its account. Set `REVSCOPE_CONFIG_DIR` to keep accounts apart.
- To open the dashboard, the owner runs `revscope password-reset --email dana@example.com` and follows the emailed link. Setting a password signs out the CLI, so run `revscope login --email dana@example.com --password-stdin` afterwards.

Use of the service is subject to the [terms of service](https://revscope.co/terms.md).

## Start collecting data

```sh
revscope install snippet   # Prints the snippet. Add it to the <head> of every page.
revscope install verify    # Exits 7 if the tracker isn't in the page's HTML yet.
```

To attribute revenue, connect a payment provider. `-` reads the key from stdin, which keeps it out of shell history and the process list.

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

## Query analytics

Queries are one read-only SQL statement against the project's SQLite analytics database. Read the schema first:

```sh
revscope tables
revscope schema --table pageviews
```

Top pages:

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

Visits and revenue by channel. Money columns are integer thousandths of the currency unit, so divide by 1000.

```sh
revscope query "SELECT COALESCE(l.referrer_type, 'other') AS channel,
    COUNT(DISTINCT l.visitor_timestamp_id) AS visits,
    COALESCE(SUM(pay.amount), 0) / 1000.0 AS revenue
  FROM landings l
  LEFT JOIN payments pay
    ON pay.attributed_visitor_timestamp_id = l.visitor_timestamp_id AND pay.status = 'ok'
  GROUP BY channel ORDER BY revenue DESC"
```

- Results are limited to 500 rows a page. Use `--limit` and `--offset` with an `ORDER BY`, or `--all` to follow the pages. Offsets stop at 5000, so narrow a larger result with `WHERE`.
- New events reach the database every five minutes, so the latest ones may not show up in `query`. `revscope install status` counts those still waiting.
- On an account with several projects, pass `--project <name>` or set `REVSCOPE_PROJECT`.
- To read analytics from an MCP client instead of a shell, use [the MCP server](https://revscope.co/docs/ai.md).
- To see the dashboard with sample data and no account, open [the live demo](https://revscope.co/demo).

## Scripting

Add `--json` to any command to print its result as JSON on stdout, failures included. Run `revscope <command> --help` for every flag. The [CLI README](https://github.com/eloff/revscope/blob/main/cli/README.md) has the full reference.

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

## Reading this site

Every page except the signup and billing forms has a Markdown version: add `.md` to its path, as in `https://revscope.co/docs/consent.md`, or request the page with `Accept: text/markdown`. [llms.txt](https://revscope.co/llms.txt) lists them, [llms-full.txt](https://revscope.co/llms-full.txt) has them all in one file, and [the sitemap](https://revscope.co/sitemap.xml) lists the HTML pages.

## Contents

Every page with a Markdown version.

### Site

- [Home](https://revscope.co/index.md): RevScope connects your web traffic to your payments so you see which channels and content convert. Grow revenue faster.
- [Data Processing Agreement](https://revscope.co/dpa.md): Data Processing Agreement between RevScope and customers for website visitor analytics processed on the customer's behalf.
- [Frequently asked questions](https://revscope.co/faq.md): Frequently asked questions about RevScope revenue attribution analytics: trials, pricing, privacy, integrations, and more.
- [Traffic-based plans to match your growth](https://revscope.co/pricing.md): Traffic-based plans that match your growth. Start with the free plan, paid plans from $12/month.
- [Privacy Policy](https://revscope.co/privacy.md): How RevScope collects, uses, and protects data on revscope.co and as a processor for customer websites.
- [Startup runway calculator](https://revscope.co/startup-runway-calculator.md): Free startup runway calculator. Enter cash, burn, revenue, and growth to project how long your cash lasts and when you break even.
- [Terms of Service](https://revscope.co/terms.md): Terms of Service for using RevScope revenue attribution analytics at revscope.co.

### Docs: Start here

- [RevScope documentation](https://revscope.co/docs.md): Everything you need to get up and running with RevScope revenue attribution analytics.
- [Getting started](https://revscope.co/docs/getting-started.md): Install the RevScope tracking script and connect your payment provider in under 10 minutes.
- [Self-hosting](https://revscope.co/docs/self-hosting.md): RevScope is open source. Run it on your own server for free with Docker.

### Docs: Tracking

- [Tracking script](https://revscope.co/docs/tracking-script.md): Configuration reference for the RevScope tracking script: attributes, SPA support, and automatic tracking.
- [GDPR and ePrivacy](https://revscope.co/docs/gdpr.md): Understand GDPR and ePrivacy consent requirements, why consent-dependent analytics miss traffic, and how RevScope provides privacy-friendly revenue attribution.
- [Privacy laws](https://revscope.co/docs/privacy-laws.md): Understand how privacy laws outside the EU affect analytics, consent, and attribution, and how RevScope adapts its privacy-friendly behavior by region.
- [Ad blockers](https://revscope.co/docs/ad-blockers.md): Route the RevScope tracker and ingest requests through a first-party CNAME or reverse proxy for more complete analytics in browsers with ad blockers.
- [Consent](https://revscope.co/docs/consent.md): Connect RevScope to your consent banner: set_consent, consent_status, and when to show a cookie banner.
- [Custom events](https://revscope.co/docs/custom-events.md): Track signups, clicks, and any other action with the RevScope JavaScript API or declarative HTML attributes.
- [Custom metadata](https://revscope.co/docs/custom-metadata.md): Attach custom key/value metadata to RevScope sessions with config, the JavaScript API, or URL parameters.

### Docs: Insights

- [Funnels](https://revscope.co/docs/funnels.md): Measure drop-off across pageviews, events, and payments with RevScope funnels.
- [Connect AI agents](https://revscope.co/docs/ai.md): Ask RevScope about your analytics in the dashboard, or connect Claude, Codex, ChatGPT, Cursor, Grok, or other AI agents via MCP.

### Docs: Integrations

- [Integrations](https://revscope.co/docs/integrations.md): Connect Stripe, Shopify, Square, Lemon Squeezy, Polar, Dodo Payments, and Google Search Console to RevScope.
- [Stripe](https://revscope.co/docs/integrations/stripe.md): Connect Stripe to RevScope and accurately attribute payments and subscriptions to the sessions that generated them.
- [Shopify](https://revscope.co/docs/integrations/shopify.md): Connect Shopify to RevScope to sync orders, refunds, and subscription contracts from your store.
- [Square](https://revscope.co/docs/integrations/square.md): Connect Square to RevScope to sync payments, refunds, subscriptions, and invoices.
- [Lemon Squeezy](https://revscope.co/docs/integrations/lemon-squeezy.md): Connect Lemon Squeezy to RevScope to sync subscriptions and subscription invoices.
- [Polar](https://revscope.co/docs/integrations/polar.md): Connect Polar to RevScope to sync subscriptions, orders, and refunds.
- [Dodo Payments](https://revscope.co/docs/integrations/dodo-payments.md): Connect Dodo Payments to RevScope to sync payments, subscriptions, and refunds.
- [Google Search Console](https://revscope.co/docs/integrations/google-search-console.md): Connect Google Search Console to RevScope to see which search queries drive traffic and revenue.
- [Import from Google Analytics](https://revscope.co/docs/integrations/google-analytics.md): Bring your Google Analytics 4 history into RevScope, and see what imported data can and can't show.

### Blog

- [Blog](https://revscope.co/blog.md): News, guides, and ideas on revenue analytics from the RevScope team.