SEO docs that turn site evidence into fixes

Run an SEO audit on your own computer. It crawls your site, reads the Google data you choose to connect, and returns reports that show the evidence behind each recommendation.

You can use it yourself in a terminal or give the same reports to an AI agent through skills, JSON, or a local MCP server. Either way, the analysis comes from the same code.

Install the CLI and agent skills

An agent gets the best result with both parts of the project:

• The CLI crawls sites, connects Google, and runs deterministic reports through the terminal or MCP.
• Agent skills teach the agent which report to run, how to read incomplete evidence, and what to verify before changing a site.

Install both when an agent will do the work:

npm i -g seo
npx skills add iannuttall/seo

The CLI still works on its own for people, scripts, and CI. The skill can teach an agent about the reports, but it still needs access to the CLI to run them.

Get your first useful report

You need Node 22 or newer. With the command installed, start guided setup:

seo start

The setup opens Google sign-in, lets you choose a Search Console property, offers a matching GA4 property, and saves those choices as a local project profile. Then run:

seo report

The main report checks the data that is available, tells you which sections could not run, and points you to a small number of focused follow-ups. The getting started guide walks through the result and the local files created during setup.

You can start before connecting Google.

seo report --url https://example.com

That run creates a bounded local crawl. It labels Search Console work as skipped until you add a property, rather than guessing at traffic or rankings.

Get to the right fix faster

A technical baseline starts with a crawl. A question about underperforming page-one queries needs Search Console evidence instead. The focused report gets you to the affected queries and pages without unrelated crawl findings.

The CLI includes 52 discoverable reports. They cover jobs such as:

• finding low-CTR rankings on page one and realistic page-two opportunities;
• checking one page before a rewrite, redirect, canonical change, or release;
• finding broken URLs that still have evidence of search value;
• comparing saved crawls after a deploy;
• separating a real decline from a partial or unfinished data window;
• inspecting technical eligibility for search and AI search features.

Browse the report catalog by goal. The crawler guide explains the page evidence behind technical findings.

Add post-click context when it changes the priority

Search Console provides first-party search performance and property access. GA4 is optional. It adds post-click evidence such as landing-page sessions, engagement, and known referral sources.

Both integrations are read-only. Tokens, project profiles, caches, and saved crawls stay on your machine. The Google data guide explains what each source can establish, where its numbers can be incomplete, and how local sign-in works.

Let an agent act without redoing the analysis

Agents should start with a compact result, inspect its status and caveats, then ask for detail on the affected pages or queries. Loading every report schema and every raw row into a conversation burns context without improving the answer.

Know where each conclusion stops

SEO data is messy. Search Console hides some queries, GA4 can withhold or process data later, crawls stop at configured limits, and a site can change between collection and review.

The reports keep observed evidence separate from findings. They also carry date ranges, limits, skipped sections, partial-data states, and verification steps. A missing row does not quietly become zero. An intentional noindex or canonical does not automatically become a defect either.

Questions and bugs belong on GitHub

Open a GitHub issue for ordinary questions and bugs. Leave tokens, account identifiers, private URLs, and client reports out of public issues. Suspected vulnerabilities belong in the private security reporting flow.