In short
- npx serpkin signs you in, connects your agent, registers the site and uploads a route map. It's safe to re-run.
- npx serpkin check <preview-url> exits 1 on SEO regressions, so it works as a CI step.
- Your agent key lives in ~/.config/serpkin/credentials.json and SERPKIN_API_KEY, never in the repository.
- .serpkin.json holds the server and site id, no secrets. Commit it.
The Serpkin CLI connects your coding agent, registers your site and checks preview deploys. It needs Node 22 or newer and runs with npx, so there's nothing to install. Every command below is safe to re-run.
Commands
| Command | What it does |
|---|---|
npx serpkin | Setup: sign in, connect your agent, register the site and upload the route map. Same as serpkin init. |
npx serpkin check <url> | Compare a preview deploy with production. Exit code 1 on regressions, 2 on errors. |
npx serpkin verify | Check site ownership through the verification file or DNS record. |
npx serpkin status | Site, ownership, data level, next mission and credits. |
npx serpkin next | The next mission in one line. Fast and cached; --oneline stays silent when offline. |
npx serpkin routes | Print the route map; --upload sends it. |
npx serpkin weekly | Add GitHub Actions: a weekly mission pull request and the preview SEO check. |
Setup
$ npx serpkin Open https://serpkin.com/cli and confirm the code BCDF-GHJK ✓ Signed in. Key saved to ~/.config/serpkin/credentials.json (outside this repo) ✓ Site registered: https://acme.dev (.serpkin.json saved; it holds no secrets)
Sign-in opens https://serpkin.com/cli with a short code. Confirm it matches your terminal and approve: that creates an agent key named after your machine, which you can revoke in Settings → Agent setup. The CLI then detects your framework, connects Claude Code, Cursor or Codex, registers the site and uploads a route map (URL path to source file). Unless you pass --no-scan, it runs the first scan and shows your first mission.
Check a preview
$ npx serpkin check https://acme-git-seo.vercel.app ✓ No SEO regressions across 6 pages.
It compares up to 25 paths on the preview and on production (by default the homepage plus up to 10 known pages) and fails on HTTP errors, a noindex added in the page's robots meta tag, a removed title, meta description or H1, a broken canonical, or a failing robots.txt or sitemap. Problems that already exist in production are warnings, not regressions. Header-level noindex on a preview is a warning too, because hosts such as Vercel add it to every preview.
Weekly pull requests
npx serpkin weeklyWrites .github/workflows/serpkin-weekly.yml, and the preview check .github/workflows/serpkin.yml if it's missing, then prints the gh secret set commands to run. Existing files are kept; --force replaces the weekly workflow. See Weekly pull requests.
Options
| Option | What it does |
|---|---|
--url <url> | Production URL, or a preview URL if the site isn't live yet. |
--server <origin> | Serpkin server. Default: $SERPKIN_SERVER, then .serpkin.json, then https://serpkin.com. |
--agent <list> | Which agents to connect: claude, cursor, codex (comma-separated). |
--plugin | Claude Code: install the Serpkin plugin without asking. |
--app <dir> | App directory in a monorepo, for example apps/web. |
--ownership <how> | file, search-console or skip. |
--description, --audience, --country, --language | Site details for registration. |
--login | Sign in again even if a key is stored. |
--paths </a,/b> | check: the paths to compare (max 25). |
--site <id> | Site id. Default: .serpkin.json or $SERPKIN_SITE_ID. |
--upload | routes: upload the route map. |
--force | weekly: replace an existing weekly workflow. |
--json | Machine-readable output. |
--yes, -y | Accept defaults and never prompt. |
--no-browser | Don't open a browser. |
--no-scan | init: skip the first scan and first mission. |
Without a terminal (in CI) or with --yes, the CLI never prompts. When it needs something it can't default, it stops and names the flag to pass.
Files and environment
| Item | Where | Notes |
|---|---|---|
| Agent key | ~/.config/serpkin/credentials.json | Mode 600, never in the repository. |
| .serpkin.json | Repository root | Server, site id and origin. No secrets; commit it. |
| SERPKIN_API_KEY | Environment | The key your agent's MCP config reads. |
| SERPKIN_SERVER | Environment | Overrides the server. The key is only ever sent to this server, or to https://serpkin.com when unset. |
| SERPKIN_SITE_ID | Environment | Site id for commands such as check, when there's no .serpkin.json. |
{
"server": "https://serpkin.com",
"site_id": "<your site id>",
"origin": "https://acme.dev"
}What leaves your machine
Serpkin receives your site URL, the answers you give during setup, the route map (URL paths and the file names that serve them, up to 2,000 routes) and your computer's hostname at sign-in, used to name the agent key. It never receives your source code, environment files or repository contents: to build the route map, the CLI reads package.json and the file names in your routes folder, not their contents. More in Data and privacy.