# Read Virent analytics and check installs from a terminal.

> Install the Virent command line (@virent.app/cli) to read analytics with an API key and validate a publishable key against your site from a terminal or an AI agent.

Canonical: https://stage.virent.app/docs/cli
Last updated: 2026-10-27

The Virent CLI wraps the public API for scripts, CI jobs and AI coding agents. Every command prints JSON.

## Install

```bash
npx @virent.app/cli --help
```

Or install it globally for the `virent` command:

```bash
npm install --global @virent.app/cli
```

It needs Node.js 20 or later and has no dependencies.

## Read analytics

Reading analytics needs a private API key (`vnt_sk_`) from **Settings → Connection** on a plan that includes the read API. See [Keys and secrets](/docs/workspace/keys).

```bash
export VIRENT_API_KEY=vnt_sk_…
virent analytics overview --website <website-id>
virent analytics pages --website <website-id> --from 2026-10-01 --to 2026-10-27
virent analytics timeseries --website <website-id> --interval hour --from 2026-10-26
```

| Report | What it returns |
| --- | --- |
| `overview` | Human analytics totals: pageviews, events, sessions, bounces and visitors |
| `timeseries` | Pageviews and sessions per hour or day |
| `traffic` | Totals, time series and goal conversions in one call |
| `pages` | Pageviews per page path |
| `referrers` | Sessions per referrer and traffic source, including AI referrers |
| `visitors` | Visitors by browser, device, operating system and country |

The range defaults to the last 7 days. `--timezone` takes an IANA time zone and defaults to `UTC`. Each report is one operation in the [OpenAPI specification](/openapi.json).

## Check an install

Validate a publishable key (`vha_pk_`) against a page on your site:

```bash
virent install check --key vha_pk_… --url https://www.example.com/
```

The CLI sends one pageview to browser ingest with `dryRun=1` from that page's origin. Virent checks the key, the allowed origin and host, the plan and the rate limits, and stores nothing. A `validated` event means the browser script with that key will be accepted on that site.

## Other commands

| Command | What it does |
| --- | --- |
| `virent openapi` | Prints the OpenAPI 3.1 description of the public API |
| `virent --version` | Prints the CLI version |
| `virent --help` | Lists commands and options |

Errors go to stderr with exit code 1. They include the API's error message and, when rate limited, the `Retry-After` seconds. `--base-url` (or `VIRENT_API_URL`) points the CLI at another Virent origin.

## Use with AI agents

Coding agents can run the CLI directly. Give the agent the key through `VIRENT_API_KEY` in its environment, never in a chat message, and ask it to run `virent --help` first.