SEO documentation

Run an SEO audit on your own computer. It crawls your site, reads the Google data you choose to connect and shows why each recommendation was made.

Connect an optional research provider when you need keyword ideas, current result snapshots, domain footprints, competitor discovery or keyword gap and referring-link research.

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 skill

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

• The CLI crawls sites, connects Google, and runs consistent reports through the terminal or MCP.
• The agent skill teaches the agent which report to run and what to verify before changing a site.

One command installs the CLI:

npm i -g seo

Guided setup offers the agent skill during onboarding, so there is no separate command to remember. You can also add the skill later with seo skill install.

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 optional traffic analytics for context, 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 crawls the site without using Search Console. Connect Google later when you want search performance and query data.

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 74 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;
• researching keywords, ranking pages and recurring search competitors;
• filtering competitor terms through Search Console data and programmatic page patterns;
• finding location-specific demand and repeated local page patterns before checking a few exact local results.

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 search performance and query data. Traffic analytics is optional. Google Analytics adds sessions, engagement, conversions, geography and known referral sources. Clicky adds observed page views and landing-page visits.

Analytics connections are read-only. Tokens, provider secrets, project profiles, caches, and saved crawls stay on your machine. The Google data guide explains local Google sign-in. Optional provider packages keep their setup instructions in their package repositories.

The research provider guide covers provider setup, local spend limits, caching and the reports that can use outside estimates.

Let an agent act without redoing the analysis

Agents should start with the main report, then open the affected pages or queries for the few findings that deserve action.

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.