seo

The seo command turns crawl, Search Console, connected traffic analytics, and optional research-provider data into work you can inspect and ship. Find technical blockers, recover existing demand, research new keywords and competitors, review programmatic page patterns, and catch regressions after a release.

Who this is for

• People running their own sites who want a clear audit and a ranked list of fixes, without learning a heavy dashboard.
• AI agents that need real crawl, Search Console, traffic analytics, keyword, result, domain, competitor, and link evidence through MCP and one packaged SEO skill instead of screenshots or guesses.
• Developers who want to embed the same report engine in a script, a CI job, or a TypeScript app.

Quick start

Requires Node 22 or newer.

npm i -g seo
seo start
seo report

The setup walks you through Google sign-in, your Search Console property, an optional traffic analytics connection, and a local project profile. Public releases can include the shared Google app. If it is unavailable in your build, setup guides you through adding your own desktop OAuth client.

DataForSEO, Semrush, and Ahrefs are optional research providers built into the main package. Connect one only when external result, keyword, domain, competitor, or link evidence would change the decision.

That is the normal path. The seo command is then available in every terminal, script, CI job, and local MCP client on the machine.

The main report uses the evidence you have, explains what it could not check, and recommends a short list of follow-up commands. You can start with a local technical report before connecting Google: seo report --url crawls the site and returns findings and an action list with no sign-in at all.

Running seo help shows the shape of the tool:

Run SEO audits, find what needs fixing, and ship the changes with your agent.

Start here
  seo start                                Connect first-party data and save a project profile
  seo report                               Run the main SEO report for the default project
  seo report --site sc-domain:example.com  Run without a profile
  seo report --url https://example.com     Start with a local technical report

Projects
  seo projects list  List saved project profiles
  seo projects add   Create or update a project profile
  seo sites          List Search Console properties
  seo doctor         Check local auth and config

Act on a report
  seo refresh-priorities  Rank the next best SEO actions
  seo quick-wins          Find ranking 4-10 low-CTR wins
  seo second-page         Investigate URLs averaging positions 10-20
  seo technical-watch     Crawl and index-monitor a site

Agent and power tools
  seo report --json    Run the main report as structured JSON
  seo export diagnose  Export report data to CSV
  seo mcp install      Install SEO tools into MCP clients
  seo skill list       Show the packaged SEO skill
  seo reports list     Discover every structured report

Use `seo help <command>` or `seo <command> --help` for command help.
Use `seo help all` for the longer command list.

What you get

• Find technical blockers across metadata, links, indexability, canonicals, structured data, performance, security, mobile, international SEO, and social previews.
• Rank the work using affected URLs, rule severity, search visibility, and analytics value instead of treating every warning equally.
• See why a finding matters, what evidence supports it, how to fix it, and how to verify the change.
• Save and compare crawl reports without running the same crawl again.
• Measure SEO changes with matched before and after Search Console windows.
• Discover keyword ideas, compare market estimates, inspect current results, and keep useful terms in local saved sets.
• Find recurring search competitors, inspect their ranking pages, and filter possible keyword gaps through Search Console data and existing provider rankings.
• Find repeatable Search Console searches and review planned terms, comparison pairs or other useful combinations.
• Find repeated page patterns on your site and competitor sites, then check what information a useful new page would need.
• Find location-specific Search Console demand and repeated local page patterns, then add a few exact local result snapshots when the decision needs them.
• Give scripts and agents deterministic JSON, Markdown, stable rule IDs, and a compact local MCP surface.

How the reports stay honest

The point of a report is to be defensible, so the design keeps a few rules:

• Observed evidence stays separate from derived findings and recommended actions. You can always see the crawl row or provider row behind a claim.
• Partial data is never reported as a zero. A capped, filtered, or sampled source says so, and it cannot support a definitive all-clear.
• Heuristics are labeled as heuristics. A convention or threshold is not presented as a search-engine rule.
• Each recommendation comes with a way to check that the fix worked, rather than a promise about rankings or traffic.

Everyday use

seo start can save a project profile, which is a local shortcut for a site, Search Console property, traffic analytics connection, and brand terms. If you have one default project, most commands need no flags.

seo report
seo refresh-priorities
seo quick-wins
seo second-page
seo technical-watch

Use --project when you have more than one:

seo report --project example
seo projects list

You can also work without a saved profile:

seo report --site sc-domain:example.com
seo report --url https://example.com
seo crawl https://example.com
seo audit-page --url https://example.com/pricing

seo report --url crawls the site and saves technical evidence. It does not pretend to know traffic, queries, or rankings until you add a Search Console property with seo start. If you have a Search Console performance download on disk, point the same report at the folder or CSV with --search-console-export. The report reads the query and page tables, keeps them separate from the crawl, and tells you which exported pages the crawl could not reach. Large page inventories return stable pages; continue with --inventory-page <number> until nextPage is null.

Run seo help for the short path or seo help all for the full command list.

Research keywords and competitors

Connect a research provider when you need independent market estimates or competitor evidence. Each connection is local and separate from Google sign-in. The main package includes DataForSEO, Semrush, and Ahrefs. DataForSEO has the broadest live coverage:

seo providers dataforseo connect
seo providers dataforseo status --check
seo providers dataforseo limits

Credentials use the system keychain when available, with a private local file fallback. Semrush Version 3 and Ahrefs API v3 use the same local credential boundary:

seo providers semrush connect
seo providers semrush status --check

seo providers ahrefs connect
seo providers ahrefs status --check
seo providers ahrefs limits

Read the Semrush guide and Ahrefs guide before running paid research. Supported reports record the applicable API units or USD cost, cache state, request limits and row counts. Cached results avoid repeating paid work during their retention window.

Use the existing report catalog. There are no separate provider-named report commands:

seo reports describe keyword-research --json
seo reports describe competitive-opportunities --json
seo reports describe domain-overview --json
seo reports describe competitor-keyword-gap --json
seo reports describe local-search-demand --json
seo reports describe pseo-patterns --json
seo reports describe pseo-opportunities --json
seo reports describe ai-mention-research --json
seo reports describe ai-prompt-observations --json

seo reports run domain-overview \
  --params '{"domain":"example.com","countryCode":"GB","languageCode":"en"}' \
  --json

Ranked-keyword exports work without provider API access. Pass one to four local DataForSEO, Semrush or Ahrefs files through the same report pipeline:

seo reports run competitor-keyword-gap \
  --params-file ./competitor-gap-run.json \
  --json

The parameter file uses researchFiles. Each item records dataset: "ranked-keywords", the local file, its provider, and the real exportedAt date. CSV, TSV, JSON, JSONL and NDJSON are supported. UTF-8 and UTF-16 CSV files are detected automatically, including Ahrefs downloads that use tabs despite a .csv name. The output keeps the detected encoding and delimiter, a SHA-256 hash, included fields, explicit column mapping, row counts, filtered historical rows, invalid rows, duplicates and caps under evidence.imports. Add columns when an export uses unfamiliar headings. Each entry maps a canonical field such as keyword, url, position or searchVolume to the source heading. Imported files can feed ranked-keywords, ranking-pages, serp-competitors and competitor-keyword-gap without adding another command or MCP tool. The research provider guide has the exact JSON format, market guidance and file limits.

The research flow now covers:

• competitive-opportunities for turning a small topic set into a focused keyword and competitor investigation order using current results, free Domain Rating observations, and optional paid link summaries;
• keyword-research, keyword-metrics, and saved-keywords for discovery, estimates, and local persistence;
• serp-results and rank-tracking for current or repeated exact market and device-specific observations;
• domain-overview, ranked-keywords, and ranking-pages for country-level domain, term, page, and repeated path evidence;
• serp-competitors for finding domains that recur across an explicit keyword set without guessing whether they are a business, publisher, directory, community, or marketplace;