Serpel CLI reference

How do you install the Serpel CLI?

The CLI is published on npm as `@serpel/cli` under the MIT license. It installs one command, serpel, ships as a single bundled file and needs Node.js 20.9 or newer.

1. 1

   Install it globally.

   npm puts the serpel command on your path. pnpm, Yarn and Bun work the same way.

   npm install -g @serpel/cli

2. 2

   Or run it without installing.

   npx downloads the latest version for a single run, which is handy in CI or on a shared machine.

   npx @serpel/cli --help

3. 3

   Check the installation.

   The command prints the CLI version.

   serpel --version
   serpel --help

The package contains dist/index.js with its libraries bundled, plus their license notices. The one optional dependency is @napi-rs/keyring, which lets the CLI keep your token in the system keyring. Without it, the CLI falls back to a file that only you can read. To update, run npm install -g @serpel/cli@latest. To remove it, run npm uninstall -g @serpel/cli.

How do you sign in to the Serpel CLI?

Browser sign-in (device login)

This is the default and needs no token to copy.

serpel auth login

1. The CLI asks Serpel for a sign-in code and prints a confirmation address and a verification code such as ABCD-EFGH. The code is valid for ten minutes. The CLI opens the address in your default browser. With --no-browser, it only prints the address, which suits servers without a desktop.
2. In the dashboard, check that the code matches, choose the permissions the token gets and approve the sign-in.
3. The CLI waits for your approval, stores the token and prints your name, email address, permissions and project restriction.

Ctrl+C cancels the wait. If the code expires or you deny the sign-in, the command exits with code 3.

Sign in with an API token

Create a token in the dashboard under Settings, API tokens, or with serpel tokens create, and hand it to the CLI. The CLI checks it with GET /me first and stores nothing if the token is invalid. Prefer --token-stdin over --token, because an argument ends up in your shell history.

echo "$SERPEL_TOKEN" | serpel auth login --token-stdin
serpel auth login --token-stdin < token.txt

Use SERPEL_TOKEN in scripts and CI

In CI you do not need serpel auth login. Set SERPEL_TOKEN and the CLI uses it for every command. The variable beats any stored token and is never written to disk.

export SERPEL_TOKEN=vsk_your_token
serpel projects list --json

Check your session or sign out

serpel auth status
serpel auth logout

auth logout revokes the stored token on the server and then deletes it locally. If the server cannot be reached, the CLI still deletes the local copy and warns that the token stays valid until you revoke it in the dashboard or it expires. A token from SERPEL_TOKEN is not touched.

How is the Serpel CLI configured?

The CLI talks to https://serpel.app unless you tell it otherwise. The first source that is set wins: the --api-url <url> flag, the SERPEL_API_URL variable, the config file (serpel config set api-url <url>), then the default. Only https:// addresses are accepted, except http:// for localhost, 127.0.0.1 and [::1]. A trailing /api/v1 is removed, and addresses with credentials, query parameters or anchors are rejected. Most people never change the address. Set it only if you use another Serpel instance.

serpel config get
serpel config get api-url
serpel config set api-url https://example.com
serpel config unset api-url

Environment variables

Where does the CLI keep your token?

• In the system keyring when one is available: Windows Credential Manager, macOS Keychain or the Secret Service on Linux. The entry uses the service name serpel and the API address as the account.
• Otherwise in credentials.json in the config directory, with permissions that only your account can read, and a warning. Under Windows, the permissions of your user profile protect the file.
• The token never appears in output, not even with --verbose or --json, and the CLI does not follow redirects, so the token cannot be sent to another address.

Which global flags does the CLI have?

These flags work with every command and can come before or after it.

Which commands does the Serpel CLI have?

Every command accepts --help and prints its flags. Arguments such as <id> stand for IDs you get from other commands, for example serpel projects list. Commands that delete or disconnect something send nothing until you add --yes, and exit with code 2 without it.

Account and configuration

Projects

serpel projects update takes these settings. Pass only the ones you want to change.

Crawls and audit

The --category filter accepts availability, redirects, meta, headings, indexing, crawling, links, images, security, content, performance, mobile, structured_data, ai_search, rendering, international, web_vitals, social.

Jobs

Keyword research and keyword lists

Rankings and competitors

AI visibility

Monitoring and reports

Search data, web analytics and integrations

API keys for Bing, PostHog and Plausible are read from a file with --api-key-file <path>, or from standard input with -. They are never passed as an argument and never printed. Google connections open a browser approval; --no-open only prints the address.

Tasks and recommendations

Codebase scan

serpel scan [directory] reads a Next.js project, builds a snapshot of its routes and metadata and uploads it to a project. Serpel then matches routes to crawled pages and search data and flags differences between code and live site. The snapshot contains no source code. The upload is free and needs the codebase:write scope.

The CLI never reads or sends .env files, key files, node_modules, .git or anything your .gitignore excludes, and it removes values that look like credentials. Limits: 2,000 routes, 5,000 sitemap URLs, 2 MB of JSON and 20 uploads per project and day. Answering anything but yes to the confirmation prompt ends the command with exit code 130.

serpel scan --dry-run
serpel scan apps/web --dry-run --out snapshot.json
serpel scan --project "$PROJECT_ID" --wait
serpel scan apps/web --project "$PROJECT_ID" --yes --include-text

Export

serpel export --project <id> --type <type> exports issues, keywords, rankings or tasks. --format is csv (default) or json. Without --output <file> (-o), the file content goes to standard output so you can redirect it. --crawl <id> applies to issues (default: the last completed crawl) and --list <id> to keywords.

serpel export --project "$PROJECT_ID" --type issues --format csv --output issues.csv
serpel export --project "$PROJECT_ID" --type rankings --format json > rankings.json

Billing, agents and providers

Top-ups, plan changes and the agent settings need the workspace owner role.

Which permissions do the commands need?

A token can only run commands whose scope it has. Without the scope, the API answers with HTTP 403 and the CLI exits with code 4. The REST API reference lists every scope.

How do you wait for background jobs?

Crawls, rank checks, AI visibility checks and monitoring runs run in a worker. crawl start, rankings run, ai run and monitoring run print the job ID and return. With --wait, the CLI checks the job every two seconds until it succeeds, fails or is cancelled, and then prints a summary. --timeout <seconds> limits the wait and only works with --wait. jobs status <jobId> --wait follows a job you started earlier.

• If the job fails or is cancelled, the CLI exits with code 8 and prints the last error.
• If --timeout is reached, the CLI exits with code 10. The job keeps running on the server.
• Ctrl+C stops waiting and exits with code 130. The job keeps running.
• Short network errors while waiting are retried up to three times.
• SERPEL_POLL_INTERVAL_MS changes the check interval.

serpel crawl start --project "$PROJECT_ID" --wait --timeout 900
serpel jobs status "$JOB_ID" --wait

How does pagination work?

List commands accept --limit <n> (1 to 200, default 50) and either --page <n> (from 1) or --offset <n>. When more entries exist, the CLI prints the range and the flags for the next page on standard error. With --json, the total is in pagination.total.

How do you use JSON output in scripts?

With --json, the CLI writes only JSON to standard output. Hints, warnings and progress go to standard error, and colours are off. Lists come as { "data": [...], "pagination": { "limit", "offset", "total" } }. Single objects and actions return the object itself. Errors are printed to standard output as an object and set the exit code.

{
  "error": {
    "code": "not_logged_in",
    "message": "Not signed in to https://serpel.app."
  }
}

API errors keep the code of the API, such as validation_error or unauthorized. Local errors use their own codes: usage_error, not_logged_in, network_error, timeout, job_failed, job_cancelled, wait_timeout, interrupted and webhook_failed. Some errors add a details field.

serpel projects list --json | jq -r '.data[] | "\(.id) \(.domain)"'
PROJECT_ID=$(serpel projects list --json | jq -r '.data[] | select(.domain == "example.com") | .id')
JOB_ID=$(serpel crawl start --project "$PROJECT_ID" --json | jq -r .job.id)

What do the exit codes mean?

How do you run the CLI in GitHub Actions?

Create a token with only the scopes the job needs, restrict it to one project and store it as the repository secret SERPEL_TOKEN. The CLI reads that variable on every run and never stores it.

serpel tokens create --name "GitHub Actions" --scope projects:read --scope audit:read --scope audit:write --project "$PROJECT_ID" --expires-in-days 90

The workflow below crawls the site every Monday, waits for the crawl and fails when the latest crawl contains errors. The install step pulls @serpel/cli from npm; pin a version such as @serpel/cli@0.1.0 if you want reproducible builds.

name: Serpel crawl
on:
  schedule:
    - cron: "0 6 * * 1"
  workflow_dispatch:
jobs:
  crawl:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install the Serpel CLI
        run: npm install -g @serpel/cli
      - name: Crawl the site and fail on errors
        env:
          SERPEL_TOKEN: ${{ secrets.SERPEL_TOKEN }}
          SERPEL_PROJECT_ID: ${{ vars.SERPEL_PROJECT_ID }}
        run: |
          serpel crawl start --project "$SERPEL_PROJECT_ID" --wait --timeout 900
          serpel audit issues --project "$SERPEL_PROJECT_ID" --json > issues.json
          jq -e '.counts.error == 0' issues.json

How do you troubleshoot the CLI?

• --verbose prints the method, URL, status and duration of every request to standard error, without headers, bodies or the token.
• serpel config get shows which API address applies and where it comes from.
• “Endpoint not found (HTTP 404)” or “The API response is not valid JSON” usually means a wrong API address. Run serpel config get and check --api-url and SERPEL_API_URL.
• If the system keyring is not available, for example on Linux without a running Secret Service, the CLI stores the token in credentials.json and prints a warning.
• Exit code 3 means the token is missing, invalid, expired or revoked. Sign in again or create a new token.