SEO CLI setup check

Run this when setup, Google sign-in or a saved project is not behaving. It checks the local pieces in order and tells you what to fix first.

Install and run the check

Install the CLI first. If setup is the part that has gone wrong, run this check before trying to connect the site again.

Runafter install

Install the SEO CLI globally.

npm i -g seo

Run setup after installation.

seo start

Check local sign-in, scopes, configuration, and defaults.

seo doctor

What the check tells you

Check your SEO CLI login, Google permissions, OAuth client and saved project settings. Get the exact next step for each failed setup check without guessing.

Best for: Sign-in, project selection, or provider-backed reports are failing.
Needs: Local SEO configuration and paths
You get: Check your SEO CLI login, Google permissions, OAuth client and saved project settings. Get the exact next step for each failed setup check without guessing.
Use next: Review SEO performance

Every report follows the same rules for missing data and outside estimates.See how report data works.

What you need before you run it

The report uses the information below. Optional sources are only used when you ask for them.

Local SEO configuration and paths

Provides the config directory, saved defaults, OAuth client source, and project settings.

Local Google token and granted scopes

Shows whether sign-in exists and includes the read-only Search Console and Analytics scopes.

Use a different report for these jobs

These jobs need a different report or a manual review.

Google sign-in and the local project are working and you need to find SEO problems on the site itself.

Run a site crawl. It fetches site evidence and applies the technical checks. Setup check only verifies the local configuration and access needed to run other reports.

Sitemap health check and technical site crawl

The setup checks pass but a provider still returns missing, delayed, partial, or unexpected data.

No automated setup report can recover data that the provider did not return. Review the selected property, date range, provider limits, Google account access, and the report source status. Setup check can confirm local credentials and scopes, but it cannot make unavailable rows appear.

Needs more evidence

Use the check with an agent or in code

The command above is enough for most work. These options let an agent, script or application run the same check with explicit input and structured output.

Use the report catalog when an agent, script or CI job needs predictable JSON instead of the normal terminal output. Check the current input first, then run the check with the validated parameters.

Check the current input before the agent or script runs the check.

seo reports describe setup-check --json

Once the input is valid, run the check through the report catalog.

seo reports run setup-check --params '{}' --json

An MCP agent follows the same two-step flow. It inspects the current schema, fills the required fields and only then runs the check.

Ask the MCP server for the current check input.

{
  "id": "setup-check"
}

Run the check after the agent has checked and filled the input.

{
  "id": "setup-check",
  "params": {}
}

Install the package in a Node 22 project when your application needs to run the check directly. The result includes the same evidence, warnings and limits returned through the CLI and MCP server.

Add the SEO package to your project.

npm install seo

Run the check from your TypeScript application.

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'setup-check',
  {},
)

console.log(result)

What to do next

Fix the first failed setup check because later failures may be a consequence of it. Run the setup check again after each change until the saved project and Google connection pass together.

01Run `seo start` if the installation still needs a project profile.
02Run the search performance overview after auth and project defaults pass.

See what changed in Search Console and which pages, queries, countries or devices explain the movement before choosing what to investigate next.

SEO performance report