Compare two saved crawls and see exactly what changed

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 changed between these two crawl snapshots?

• You need to verify a deployment, migration, or technical cleanup.
• Both crawls used comparable scope and settings.

Command facts

Report id

compare-crawls

Execution

Local process

Outputs

JSON and Markdown

Example parameters

after, before, site

Agent discovery

seo reports describe compare-crawls --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.

• You have one saved baseline but still need to fetch the current site before comparing it. Recommended report: Monitor crawl changes. Run crawl diff. It fetches the current limited scope, compares it with the compatible monitoring snapshot, and keeps failures or scope changes separate from real regressions.
• You need to know which release, edit, or external event caused a crawl change. No automated report can prove the cause from two crawl snapshots. Compare deployment records, source changes, server logs, and the affected page templates. This report can still identify when the evidence changed and which URLs or rules need that investigation.

Data sources and inputs

• Earlier saved crawl report. Provides the baseline pages, issues, config, limits, and source status.
• Later saved crawl report. Provides the current snapshot and its own scope, caps, failures, and evidence.

What this report checks

• Compares crawl configuration, scope, completion, caps, and source status before treating totals as comparable.
• Diffs pages, issue instances, grouped rules, and summary counts with stable ordering.

How it works

• Matches stable page and issue identities, separates additions, removals, regressions, recoveries, and unchanged evidence.

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

Compare two saved crawl snapshots. Agents and CI should inspect the live schema before their first run.

seo crawl-reports --compare latest --against previous

seo reports describe compare-crawls --json

seo reports run compare-crawls --params '{"after":"latest","before":"previous","site":"sc-domain:example.com"}' --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": "compare-crawls"
}

{
  "id": "compare-crawls",
  "params": {
    "after": "latest",
    "before": "previous",
    "site": "sc-domain:example.com"
  }
}

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(
  'compare-crawls',
  {
  "after": "latest",
  "before": "previous",
  "site": "sc-domain:example.com"
},
)

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

• New, resolved, and persistent page and issue changes with before and after summary values.
• A plain-language headline, comparability status, warnings, and caveats for scope or completeness differences.
• Check crawl scope and failures first. A disappeared issue is a recovery only when the page remained testable in the after crawl.

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

• A missing page, blocked fetch, or changed crawl limit can make an issue disappear without being fixed.

What to do next

1. Audit representative regressions directly.
2. Run affected URLs when a changed rule spans many pages.

Related reports

• 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.
• Audit one page. Inspect one live URL before changing its metadata, canonical, directives, structured data, links, or content.
• Monitor crawl changes. Crawl the same limited URL scope again and find technical or page changes since the previous monitoring run.

Browse all reports in Crawling and technical checks.