Getting started with Serpkin

Serpkin gives your coding agent one SEO mission at a time: the change worth making next on your site, with the files to edit and the checks that prove it worked. This page takes you from nothing to your first verified mission. You need a website repository, Node 22 or newer, and Claude Code, Codex or Cursor. Setup takes about five minutes, and the Free plan is enough to follow along.

#Set up in five minutes

1. Run the setup command in your website's repository

   npx serpkin

   It opens serpkin.com/cli in your browser with a short code such as BCDF-GHJK. Check that it matches your terminal and approve. That creates an agent key named "Serpkin CLI on your machine". The key is saved outside your repository, and you can revoke it any time in Settings, under Agent setup.

2. Let it detect your framework and connect your agent

   The CLI detects Next.js (App and Pages Router) fully, and Astro, SvelteKit, Nuxt and Remix as best effort. In a monorepo it asks which app is the website. Then it connects the agents it finds: for Claude Code it offers the Serpkin plugin, for Cursor it writes .cursor/mcp.json and a project rule, and for Codex it adds the server to ~/.codex/config.toml and a short section to AGENTS.md.

3. Register the site and prove you own it

   The CLI registers your site and uploads a route map: a list of URL paths and the source files that render them, so missions can name the files to change. Your source code isn't uploaded. To unlock full scans, prove ownership with Google Search Console or by deploying public/serpkin-verification.txt and running npx serpkin verify.

4. Ask your agent for the first mission

   In Claude Code, run /serpkin:next in a new session. In any agent, ask: "What should I do for SEO?" The agent calls Serpkin, gets the top mission and starts working on it.

5. Ship it, then verify

   Your agent makes the change in your repository. Check the preview deploy with npx serpkin check <preview-url> (or /serpkin:ship <preview-url> in Claude Code), merge and deploy as you normally do, and ask the agent to verify the mission in production.

#What you see in the terminal

Setup prints one line per step. If it can, it starts the first scan and shows your first mission before it finishes, usually in under a minute. An illustrative run on a Next.js site:

$ npx serpkin
✓ Signed in. Key saved to ~/.config/serpkin/credentials.json (outside this repo)
✓ Next.js (app router): 14 routes
✓ Claude Code: installed the Serpkin plugin. Try /serpkin:next in a new session.
✓ Site registered: https://acme.dev (.serpkin.json saved; it holds no secrets)
✓ Route map uploaded. Missions can now name the files to change.
Scanning your site for the first missions (usually under a minute)…
✓ 6 missions ready for acme.dev.
  First mission: Remove unintended noindex from public pages

If the scan is still running when the CLI finishes, it says so; your agent sees the missions as soon as the scan is done. Re-running npx serpkin is safe: it reuses the stored key and site, and only refreshes its own blocks in agent config files.

#Your first mission

On a new site, the first missions are usually foundation fixes from the scan: pages Google can't index, a missing sitemap, broken titles or canonicals. Each mission says what it's based on, why it comes now, which files to edit and how Serpkin will check it. Search data and Search Console add growth missions later, such as pages close to page one or topics your site doesn't cover. See Missions for the full list.

#Ship and verify

Verification is how a mission gets marked done. Serpkin checks the change itself, on the environment you name:

• Preview: before you merge, Serpkin checks the preview deploy against the mission's acceptance checks.
• Production: after you deploy, Serpkin checks the live site. A passed production check marks the mission verified and starts the result measurement.
• Results: Serpkin takes a baseline and measures again at 14 and 28 days, compared with similar pages you didn't change.

npx serpkin check <preview-url> is a separate safety net. It compares a whole preview with production and exits with code 1 when the preview would hurt SEO, for example a new noindex, a removed title or canonical, or a broken sitemap. You can run it in CI on every pull request; see Serpkin in GitHub Actions.

#Where to go next

Learn how it works

• Missions: the types, how they're ranked and how to dismiss one.
• Verification and results: what passes, and how impact is measured.
• Site watch: the regular recheck and the alerts it sends.

Set up your agent in depth

• Claude Code, Cursor or Codex.
• Weekly pull requests: let Claude Code work on the top mission every Monday.

Stuck? Troubleshooting covers sign-in, agents that don't see Serpkin and verifications that fail.