SEO crawl diff for release checks and technical SEO regressions.

Run this report from the CLI, an MCP client, or application code. Every surface uses the same report definition and returns the same evidence. JSON is the source of truth; Markdown makes it readable without hiding dates, limits, warnings, or skipped work.

What this report helps you decide

What technical or page evidence changed since the previous comparable crawl?

• A release, migration, or scheduled technical check needs a fresh comparison.
• The start URL and crawl bounds can remain comparable between runs.

Command facts

Report id

crawl-diff

Execution

Local process

Outputs

JSON and Markdown

Example parameters

startUrl, site, limit, refresh

Agent discovery

seo reports describe crawl-diff --json

Interactive prompts

Human CLI commands only

When this report is not the right tool

These cases need a different report, more evidence, or a human decision. Do not force this report to answer a question its data cannot support.

• Both crawl snapshots already exist and you need to choose the exact earlier and later report IDs yourself. Recommended report: Compare two saved crawls. Compare the saved crawls. It reads both local snapshots without fetching the site and checks their configuration and completeness before presenting changes.
• There is no compatible baseline yet and you need the first technical snapshot. Recommended report: Crawl a site for technical SEO issues. Run a site crawl and save it as the baseline. A change report cannot identify regressions from a single snapshot, but the saved crawl gives the next run something comparable.

Data sources and inputs

• Current limited same-origin crawl. Provides live responses, page evidence, issues, failures, limits, and crawl configuration.
• Previous compatible monitoring snapshot. Provides the baseline for page and technical comparisons.

What this report checks

• Crawls the requested URL set within the same-origin, depth, page, and fetch limits.
• Compares the current result with the previous run and separates regressions, recoveries, changes, failures, and scope differences.

How it works

• Runs the limited crawl, matches pages and findings consistently, then separates regressions, recoveries, additions, and removals.

The JSON result keeps dates, thresholds, limits, skipped work, and source completeness beside the finding. Missing, partial, capped, filtered, and complete data remain different states.

Run the report from the CLI

Repeat a limited crawl and compare it with the previous run. Agents and CI should inspect the live schema before their first run.

seo crawl-diff --url https://example.com

seo reports describe crawl-diff --json

seo reports run crawl-diff --params '{"startUrl":"https://example.com/","site":"sc-domain:example.com","limit":250,"refresh":true}' --json

Project profiles can fill supported property and analytics inputs for the human-facing commands. The catalog form shown here is explicit by design, so agents and CI jobs do not prompt or guess.

How an MCP agent should use it

Call seo_describe_report first so the agent sees when this report is useful and gets the current input schema. Then callseo_run_report with the validated parameters. Read the status, warnings, source limits, and skipped sections before acting on a finding.

{
  "id": "crawl-diff"
}

{
  "id": "crawl-diff",
  "params": {
    "startUrl": "https://example.com/",
    "site": "sc-domain:example.com",
    "limit": 250,
    "refresh": true
  }
}

Use a follow-up report returned by the result instead of guessing the next tool. The local MCP server and CLI use the same report definition and evidence. Their outer transport envelopes differ.

Use the report in a TypeScript app

Install seo as a project dependency, then call the same report catalog used by the CLI and MCP. executeReportrejects an unknown report id or invalid parameters. Provider and runtime failures come back as structured results withisError set.

npm install seo

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'crawl-diff',
  {
  "startUrl": "https://example.com/",
  "site": "sc-domain:example.com",
  "limit": 250,
  "refresh": true
},
)

console.log(result)

The TypeScript library guide also covers direct core functions, schema discovery, and the difference betweenexecuteReport and runReport.

What comes back and how to read it

• Current crawl evidence plus new, resolved, and changed technical or page findings.
• A saved comparison snapshot, data status, warnings, and caveats for caps, failures, and non-comparable scope.
• Check fetch and scope changes before issue deltas. A missing finding is only a recovery when the page remained testable.

Start with dataStatus, source details, warnings, and caveats. Then inspect the observed evidence before derived findings or suggested actions.

What this report cannot tell you

• Crawl limits, robots changes, timeouts, and client rendering can create apparent changes unrelated to a deployment.

What to do next

1. Audit representative regressions.
2. Use affected URLs for repeated rule changes.

Related reports

• Compare two saved crawls. See which pages and technical issues appeared, disappeared, or changed between two saved crawl snapshots.
• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
• Find URLs affected by a crawl issue. Open the exact URLs behind a crawl finding and turn a summary count into a limited review or fix list.

Sources behind the guidance

These primary sources define the provider data or search controls used in the interpretation above.

• Google robots.txt guidance
• Google JavaScript SEO guidance

Browse all reports in Technical monitoring.