Command line

An SEO CLI for rankings, audits and CI.

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.

  • JSON output on every command
  • Device login
  • Documented exit codes
  • Made for CI
Start for freeRead the docs
Serpel CLI
serpel auth login
serpel crawl start --project <project-id> --wait
serpel audit issues --project <project-id> --severity error --json
serpel rankings list --project <project-id> --json | jq -r '.data[] | [.keyword, .latest.position] | @tsv'

❯

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.

CommandWhat it does
serpel projectsCreate, show and update projects and manage members.
serpel crawl and serpel auditStart crawls, compare them, list issues and read Core Web Vitals.
serpel rankingsAdd keywords, run checks, read positions, history and stored results.
serpel aiAdd prompts, run ChatGPT and AI Overview checks and show citations.
serpel searchConnect Google and Bing and read clicks, impressions and positions.
serpel keywordsResearch keywords and manage keyword lists.
serpel monitoring and serpel reportsRun monitoring, manage recipients and read reports.
serpel tasks and serpel recommendationsManage tasks and act on recommendations.
serpel scanUpload route metadata from a Next.js project.
serpel exportExport issues, keywords, rankings or tasks as CSV or JSON.
serpel tokens, serpel billing and serpel agentsManage tokens, check balance and estimates, and control agent spending.

How do you install the Serpel CLI?

Terminal
npm install -g @serpel/cli
serpel auth login

The CLI is published on npm as `@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 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.

Fail a build on audit errors
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 codeMeaning
0Success.
2A usage error, such as an unknown option, or a validation error from the API.
3Not signed in, or the token is invalid.
4A missing permission or no access to the project.
7A provider problem or a rate limit.
8A job failed or was cancelled while waiting with --wait.
10The --timeout for --wait ran out. The job keeps running.

Which options work with every command?

OptionWhat it does
--jsonPrints 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-colorTurns colours off. The NO_COLOR variable does the same.
--verboseLogs 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 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.

    Terminal
    serpel --version

  2. Sign in

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

    Terminal
    serpel auth login

  3. Create a project

    Add your domain with the market you want to track.

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

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

Updated 10 Oct 2026

Keep reading