# An SEO CLI for rankings, audits and CI.

URL: https://serpel.app/developers/cli

Updated: 2026-10-10

An SEO CLI lets you run rank checks, site audits and AI visibility checks from the terminal and from CI, and read the results as JSON. The Serpel CLI is a client of the REST API with device login, documented exit codes and a `--json` flag on every command. Install it from npm with `npm install -g @serpel/cli`.

## What the Serpel CLI is built for

- **Almost the whole API:** Projects, crawls, rankings, AI visibility, search data, keywords, tasks, reports and exports, from one command.
- **JSON you can pipe:** With `--json`, stdout carries only JSON. Notes, warnings and progress go to stderr.
- **Jobs you can wait for:** Crawls, rank checks, AI checks and monitoring runs print a job ID, or wait for the result with `--wait` and `--timeout`.
- **Device login:** Sign in through the browser without copying a token. In CI, set `SERPEL_TOKEN` instead.
- **Token safety:** The token goes to the system keychain when one exists, never appears in output and is never forwarded through redirects.
- **Codebase scan:** `serpel scan` reads route metadata from a Next.js project and never uploads source code.

## What can an SEO CLI do?

An SEO CLI turns SEO work into commands that you can script, schedule and run in CI. With the Serpel CLI you create projects, research keywords, start crawls, track rankings, check AI visibility, read search data, manage tasks and export results, all from a terminal. It calls the same REST API as the dashboard, so permissions, credits and data are identical.

| Command | What it does |
| --- | --- |
| `serpel projects` | Create, show and update projects and manage members. |
| `serpel crawl` and `serpel audit` | Start crawls, compare them, list issues and read Core Web Vitals. |
| `serpel rankings` | Add keywords, run checks, read positions, history and stored results. |
| `serpel ai` | Add prompts, run ChatGPT and AI Overview checks and show citations. |
| `serpel search` | Connect Google and Bing and read clicks, impressions and positions. |
| `serpel keywords` | Research keywords and manage keyword lists. |
| `serpel monitoring` and `serpel reports` | Run monitoring, manage recipients and read reports. |
| `serpel tasks` and `serpel recommendations` | Manage tasks and act on recommendations. |
| `serpel scan` | Upload route metadata from a Next.js project. |
| `serpel export` | Export issues, keywords, rankings or tasks as CSV or JSON. |
| `serpel tokens`, `serpel billing` and `serpel agents` | Manage tokens, check balance and estimates, and control agent spending. |

## How do you install the Serpel CLI?

```bash
npm install -g @serpel/cli
serpel auth login
```

The CLI is published on npm as [`@serpel/cli`](https://www.npmjs.com/package/@serpel/cli) under the MIT license and installs the `serpel` command. It needs Node.js 20.9 or newer. To try it without installing, run `npx @serpel/cli --help`.

Technically, the CLI is built with esbuild into a single self-contained file. It bundles its dependencies, apart from an optional native module for the system keychain, so it needs no other Serpel packages on the machine that runs it. The [CLI reference](https://serpel.app/docs/cli) documents every command and option.

## How does sign-in work in the terminal and in CI?

`serpel auth login` uses device login. The CLI shows a code and opens the browser, and you approve access in the dashboard. No token is copied. The token is stored in the system keychain when one is available, otherwise in a file that only your account can read. It never appears in output, not even with `--verbose`.

In CI, set `SERPEL_TOKEN` and, if needed, `SERPEL_API_URL`. The variable takes precedence over any stored token and is never saved. Create a token with only the scopes the job needs, and limit it to one project.

## How do you use the SEO CLI in CI?

Start a crawl, wait for it, and fail the build when the audit finds errors. `--wait` ends the command when the job is done, and `--timeout` limits the wait. The `--json` output of `serpel audit issues` carries the counts by severity.

```bash
serpel crawl start --project "$PROJECT_ID" --wait --timeout 900
errors=$(serpel audit issues --project "$PROJECT_ID" --json | jq '.counts.error')
test "$errors" -eq 0
```

| Exit code | Meaning |
| --- | --- |
| 0 | Success. |
| 2 | A usage error, such as an unknown option, or a validation error from the API. |
| 3 | Not signed in, or the token is invalid. |
| 4 | A missing permission or no access to the project. |
| 7 | A provider problem or a rate limit. |
| 8 | A job failed or was cancelled while waiting with `--wait`. |
| 10 | The `--timeout` for `--wait` ran out. The job keeps running. |

## Which options work with every command?

| Option | What it does |
| --- | --- |
| `--json` | Prints only machine-readable JSON on stdout. Errors use the same format. |
| `--api-url <url>` | Sets the API base URL for one call. The default is the Serpel service. |
| `--no-color` | Turns colours off. The `NO_COLOR` variable does the same. |
| `--verbose` | Logs method, URL, status and duration of every request to stderr, without the token. |
| `--wait` and `--timeout <seconds>` | Wait for a job to finish, on the commands that start jobs. |

## What does the CLI cost, and can an agent use it?

Reading data is free. Commands that fetch live data book credits from the same public price list as the API, and new accounts start with 100 credits. Check a price first with `serpel billing estimate --operation rankCheck --keywords 100 --depth 50`, and read your balance with `serpel billing balance`.

An agent that can run terminal commands can call the CLI with `--json` and read the exit codes. Agents that support MCP can use the [MCP server](https://serpel.app/developers/mcp) instead, which needs no install.

## Get started in four steps

1. **Get the CLI** Install the bundled file for Node.js 20.9 or newer, then check that it runs.

```bash
serpel --version
```

2. **Sign in** Approve access in the browser. The CLI stores the token for you.

```bash
serpel auth login
```

3. **Create a project** Add your domain with the market you want to track.

```bash
serpel projects create --domain example.com --country US --language en
```

4. **Run your first audit** Start a crawl and wait for the summary of pages and issues.

```bash
serpel crawl start --project <project-id> --wait
```

## Frequently asked questions

### Is there an SEO CLI that runs in CI?

Yes. The Serpel CLI works in CI: set `SERPEL_TOKEN`, run commands with `--json` and use the exit codes to fail a build. A command that waits with `--wait` ends with exit code 8 when the job fails and 10 when the wait times out.

### How do I install the Serpel CLI?

Run `npm install -g @serpel/cli`, then `serpel auth login`. The package is on npm under the MIT license and needs Node.js 20.9 or newer. To try it once without installing, run `npx @serpel/cli --help`.

### Where does the CLI store my token?

In the system keychain when one is available, otherwise in a file that only your account can read. `SERPEL_TOKEN` takes precedence and is never stored. The token never appears in output, not even with `--verbose`.

### Does the CLI send my source code to Serpel?

No. `serpel scan` reads route metadata such as titles, descriptions and links from a Next.js project. It never reads `.env` files or anything listed in `.gitignore`, shows you what it will send first and asks for confirmation.