Open-Source SEO Scanner for the Command Line and Coding Agents

Package: ground-truth-seo
Needs: Node.js 22+
Ruleset: 2.0.0
License: Apache-2.0

npm install --global ground-truth-seo

Adds the ground-truth-seo command. Needs Node.js 22 or later; nothing else.

The button copies a prompt for your coding agent. The skill is a .zip for the Claude apps, or one command for Claude Code.

Set up ground-truth-seo for me. It is an open-source command line that audits a website's SEO and cites a primary source, quoted word for word, for every finding: https://www.seoscanner.app/command-line

1. Check that Node.js 22 or later is installed (node --version). If it is missing or older, stop and tell me how to install the current LTS release on my operating system.
2. Install the command line with `npm install --global ground-truth-seo` and confirm it runs with `ground-truth-seo --version`. If the global install fails on permissions, use `npx ground-truth-seo` in place of `ground-truth-seo` everywhere below.
3. Install its agent skill, which documents every command, option and output file: run `ground-truth-seo skill` in this project to write .claude/skills/ground-truth-seo/SKILL.md. For every project, pass --out ~/.claude/skills/ground-truth-seo; if you read skills from another directory, pass that instead. If the command is unavailable, download https://www.seoscanner.app/command-line/SKILL.md to the same place. Read the skill and follow its ground rules from here on.
4. Walk me through the optional API keys. Do not ask me to paste a key into this chat and do not write one into any file; give me the steps and I will set them myself.
- CRUX_API_KEY, for --crux: In the Google Cloud console, choose or create a project, enable the Chrome UX Report API, then create an API key under APIs & Services > Credentials and restrict it to that API. Documentation: https://developer.chrome.com/docs/crux/api
- AI_GATEWAY_API_KEY, for --review: In the Vercel dashboard, open AI Gateway, then API Keys, and choose Create key. Model calls are billed to that Vercel account. Documentation: https://vercel.com/docs/ai-gateway/authentication
Show me how to set each one as an environment variable in my shell profile (the command line does not read .env files) and remind me to open a new terminal afterwards. Everything else works without them.
5. Ask me which site to scan, then run `ground-truth-seo scan <url> --max-pages 50 --out scans/<host>`. Summarize the score with its arithmetic and the first recommendations from report.json, quoting sources exactly as the report stores them and adding no SEO advice of your own.
6. Finish with a short cheat sheet of the commands I will use most: scan, evaluate, diff and review.

Prerequisites

Node.js 22 or later, a current long-term support release. npm and npx come with it.
Network access to the site you scan. Evaluating, reviewing a stored snapshot and comparing reports need no access to the site.
Nothing else: no account, no database and no browser. Two optional features take your own keys: Chrome UX Report field data needs CRUX_API_KEY, and the AI review needs AI_GATEWAY_API_KEY.

Quick start

npx downloads the package and runs it, so there is nothing to install first:

npx ground-truth-seo scan https://www.example.com --max-pages 50 --out scans/example

It prints the score with its arithmetic and writes report.json, report.md and snapshot.json to scans/example. To keep the command around, install it with npm install --global ground-truth-seo and run ground-truth-seo directly; ground-truth-seo --help lists everything below.

Set up with a coding agent

Set up with an agent, above, copies a prompt for Claude Code, Codex, Cursor or any agent that can run commands. Paste it and the agent checks your Node.js version, installs the command line and its skill, walks you through the API keys without ever asking you to paste one, scans the site you name and ends with a cheat sheet of the commands you will use most.

The agent skill

The package ships an Agent Skill: one SKILL.md that teaches an agent every command, option, output file and key, how to read report.json, and the ground rules for reporting on it. The agent reports what the report says and nothing more, quotes sources exactly as stored, and keeps keys out of the conversation. The skill is rendered from the same data as --help, so it always matches the version you install.

Claude Code: run npx ground-truth-seo skill in your project to write .claude/skills/ground-truth-seo/SKILL.md. Add --out ~/.claude/skills/ground-truth-seo to make it available in every project.
The Claude apps: download the skill as a .zip and add it from the Skills section of the app's settings.
Other agents: save SKILL.md wherever your agent reads skills or instructions, or pass that directory to npx ground-truth-seo skill --out.

Commands

`scan <url>`

Fetches the site (robots.txt, sitemaps, a link crawl, host and scheme variants, a 404 probe, icons, images, llms.txt), freezes everything it fetched into a snapshot, evaluates it, and writes the report and the snapshot. It prints the score with its arithmetic, the headline and the snapshot ID.

Writes report.json, report.md and snapshot.json.

`evaluate <snapshot.json>`

Evaluates a stored snapshot without touching the network. With the same configuration flags as the scan, the new report.json is byte-identical to the scan's; with different flags, for example another --engines value, the same snapshot is judged under the new configuration.

Writes report.json and report.md.

`review <snapshot.json>`

Runs the advisory content and AI-answer review on a stored snapshot. It suggests titles, meta descriptions and main headings, lists the searches each page should answer and the questions it leaves open, drafts FAQ entries and checks llms.txt. It never changes the score or report.json.

Writes review.json and review.md.

`diff <before/report.json> <after/report.json>`

Compares two reports and prints, as canonical JSON, both snapshot IDs and scores, the new, resolved and changed findings keyed by rule, condition and URL, and whether the favicon changed.

`skill`

Writes SKILL.md, an Agent Skill that teaches a coding agent how to install and run this command line, set up its keys, and read report.json without adding claims of its own. The default directory, .claude/skills/ground-truth-seo, is where Claude Code finds project skills; pass --out to put it elsewhere.

Writes SKILL.md.

Options

The configuration options shape the audit, and the report records them, so evaluating a snapshot again needs the same flags as the scan to reproduce its report.json.

Option	Commands	What it does
`--out <dir>`	scan, evaluate, review, skill	Where to write the files. Defaults: scan-<host> for scan, the current directory for evaluate, the snapshot's directory for review, .claude/skills/ground-truth-seo for skill.
`--max-pages <n>`	scan, evaluate	How many pages to fetch: the link crawl plus pages found only in sitemaps (default 500).
`--max-depth <n>`	scan, evaluate	How many links deep the crawl goes from the home page (default 20).
`--max-extra-fetches <n>`	scan, evaluate	Budget for extra fetches: canonical targets, alternates and redirect targets (default 500).
`--engines <list>`	scan, evaluate	The search engines to audit for, comma-separated: google, bing (default both). Rules documented only by an engine you leave out become not applicable.
`--include <patterns>`	scan, evaluate	Comma-separated path glob patterns that shape the set of pages you intend to be indexed.
`--exclude <patterns>`	scan, evaluate	Comma-separated path glob patterns to leave out of that set.
`--additional-origins <list>`	scan, evaluate	Comma-separated extra origins that belong to the site and are treated as in scope.
`--staging-hosts <list>`	scan, evaluate	Comma-separated staging hosts, which should require authentication. Enables SEO-ROBOTS-09.
`--indexnow-key <key>`	scan, evaluate	Your IndexNow key, so its key file is checked. Enables SEO-SITEMAP-06.
`--house-conventions`	scan, evaluate	Also reports the house-convention (-HC) rules. They carry zero weight, so the score does not move.
`--third-party-resources`	scan, evaluate	Extends SEO-ROBOTS-05B (resources needed for rendering are crawlable) to resources served from other origins.
`--crux`	scan	Asks the Chrome UX Report API for field data for the origin and the home page, on phones and desktops, which SEO-PERF-01 judges against Google's thresholds. The key never enters the snapshot or the report. Needs `CRUX_API_KEY`.
`--review`	scan	Runs the advisory AI review right after the scan and writes review.json and review.md beside the report. Needs `AI_GATEWAY_API_KEY`.
`--review-pages <n>`	scan, review	How many pages the review reads (default 6, at most 20).
`--queries "<a;b>"`	scan, review	Searches the pages should answer, separated by semicolons.
`--queries-file <file>`	scan, review	The same, read from a file with one search per line.

Output files

File	Contents
`report.json`	The report as RFC 8785 canonical JSON: scanner and ruleset versions, snapshot ID, configuration and its hash, the score with its arithmetic, every finding with what was observed, the reason, the fix and the source quoted word for word, and the recommendations.
`report.md`	A readable report rendered from report.json.
`snapshot.json`	Everything the scan fetched: requests, responses, content-addressed bodies, DNS and TLS records and the one clock reading. Its ID is the SHA-256 of its canonical manifest.
`review.json`	The advisory review (with --review or review). Never part of the report or the score.
`review.md`	A readable view of the review.
`SKILL.md`	The agent skill (skill command): how a coding agent installs, runs and reads the command line.

Reproduce and compare

Evaluation is a pure function of the snapshot, the ruleset and the configuration, so the same three always give the same bytes. Scan once, evaluate the snapshot with the same flags, and the two reports are identical; scan again later and diff lists what changed:

ground-truth-seo scan https://www.example.com --max-pages 3 --out a
ground-truth-seo evaluate a/snapshot.json --max-pages 3 --out b
cmp a/report.json b/report.json      # no output: identical
ground-truth-seo diff a/report.json later/report.json

Each report names the snapshot it read and the ruleset it applied, so a changed score can be traced to a changed site or a changed ruleset. Determinism explains the contract and the tests that prove it.

Environment variables

The command line reads plain environment variables. It does not load .env files.

Variable	Effect
`CRUX_API_KEY`	A Chrome UX Report API key, required by --crux.
`AI_GATEWAY_API_KEY`	A Vercel AI Gateway API key, required by --review and the review command. It works on any machine; no Vercel project is needed.
`AI_REVIEW_MODEL`	The Gateway model ID the review uses (default anthropic/claude-sonnet-5.5).
`AI_REVIEW_DISABLED`	Set to 1 to turn the review off.

Getting the keys

Both keys are optional: without them a scan still runs every rule that does not need them and reports the rest as not evaluated.

CRUX_API_KEY: In the Google Cloud console, choose or create a project, enable the Chrome UX Report API, then create an API key under APIs & Services > Credentials and restrict it to that API. Provider documentation.
AI_GATEWAY_API_KEY: In the Vercel dashboard, open AI Gateway, then API Keys, and choose Create key. Model calls are billed to that Vercel account. Provider documentation.

Set each one in your shell profile, for example export CRUX_API_KEY=… in ~/.zshrc or ~/.bashrc (setx CRUX_API_KEY … on Windows), or as a secret in CI, then open a new terminal. Keys never enter a snapshot, a report or a review file, and the command line removes their values from anything it prints. The review costs one model call per page it reads, plus one for the site, billed to your Gateway account; the AI review page describes what it does and the guidelines that bound it.

What it does not do

The specification describes a rendered mode, which would load pages in a browser, and a check that compares the page served to phones and to desktops. Neither is built yet, in the command line or on this site, so the rules that need them report as not evaluated. The command line saves nothing to this site: its reports stay on your machine.

Open source: code and specification

Nothing about the scanner is hidden. The package, its tests and the specification live in the ground-truth-seo repository on GitHub. The README covers every command and option and the library API, for running scans from your own code. Report a problem in its issue tracker. The rule catalog, the source registry and the product specification are in its docs/ folder, and any change to a rule starts there. The code is licensed under Apache-2.0 and our own prose under CC BY 4.0; the quoted passages belong to their publishers.

This site runs the same package, so a scan here and a scan from your terminal apply the same rules, with the same wording and the same quoted sources. The rule catalog lists every rule.