searchconsole-cli (gsc)

Agent-first CLI for the Google Search Console API. Full endpoint coverage, JSON everywhere, easy login — built so AI agents (Claude Code, Cursor, Codex, …) can work with Search Console, and so you can tell your AI "use gsc" and it just works.

npx searchconsole-cli sites list
# or install globally:
npm install -g searchconsole-cli
gsc sites list

Why agent-first?

• JSON is the default output (stdout). Human-readable tables are the opt-in (--table).
• Errors are machine-readable: a single JSON object on stderr ({"error": {code, message, hint}}) with exit code 1 — every error includes a hint telling the agent how to fix it.
• Nothing is interactive except gsc auth login. Everything works headless via flags and env vars.
• Self-documenting: gsc docs prints a compact command reference written for LLM context windows.
• Ships with an AGENTS.md and a Claude Code skill you can copy into your projects.

Full API coverage

Search Console API endpoint	Command
sites.list	gsc sites list
sites.get	gsc sites get <property>
sites.add	gsc sites add <property>
sites.delete	gsc sites remove <property>
sitemaps.list	gsc sitemaps list -s <property>
sitemaps.get	gsc sitemaps get <url> -s <property>
sitemaps.submit	gsc sitemaps submit <url> -s <property>
sitemaps.delete	gsc sitemaps delete <url> -s <property>
searchanalytics.query	gsc query -s <property> … (all parameters)
urlInspection.index.inspect	gsc inspect <url> -s <property>

That is the complete surface of the Search Console API v1.

Setup

Log in — zero setup

gsc auth login

That's it. A browser window opens; approve access with the Google account that has your Search Console properties. Tokens are stored in ~/.config/gsc-cli/ and refresh automatically.

No Google Cloud project needed: the CLI ships with a built-in OAuth client (type "Desktop app" — Google classifies these secrets as non-confidential, the same approach used by gcloud and rclone).

Prefer your own OAuth client (e.g. for quota isolation)? Create one in the Google Cloud Console (type "Desktop app", Search Console API enabled) and:

gsc auth login --credentials-file client_secret_*.json   # the JSON downloaded from Google Cloud Console
gsc auth login --client-id … --client-secret …
GSC_CLIENT_ID=… GSC_CLIENT_SECRET=… gsc auth login --no-browser

Headless auth for agents & CI

Create a service account in a Google Cloud project (Search Console API enabled), download its JSON key, and add the service account's email address as a user of your property in Search Console (Settings → Users and permissions). Then:

gsc auth service-account ./key.json
# or, without touching any config:
export GOOGLE_APPLICATION_CREDENTIALS=./key.json

No browser, no prompts — ideal for AI agents and CI pipelines.

Auth precedence: GSC_ACCESS_TOKEN env var → service account (GOOGLE_APPLICATION_CREDENTIALS or configured) → stored OAuth tokens. Check with gsc auth status.

Usage

Properties are either domain properties (sc-domain:example.com) or URL-prefix properties (https://example.com/). Use the exact strings from gsc sites list. Set a default with gsc config set default-site <property> or GSC_SITE=<property> and drop the -s flag everywhere.

Search analytics

# Top queries, last 28 days
gsc query -s sc-domain:example.com --dimensions query --row-limit 20

# Pages × queries containing "pricing", all rows (auto-pagination)
gsc query -s sc-domain:example.com --dimensions page,query \
  --filter "query contains pricing" --all

# Daily clicks for the last 90 days, including fresh data
gsc query -s sc-domain:example.com --dimensions date --days 90 --data-state all

# Discover performance
gsc query -s sc-domain:example.com --type discover --dimensions page

All searchanalytics.query parameters are exposed: --start-date, --end-date, --days, --dimensions (query, page, country, device, date, searchAppearance), --type (web, image, video, news, discover, googleNews), repeatable --filter "dimension operator expression" (operators: contains, equals, notContains, notEquals, includingRegex, excludingRegex), --row-limit, --start-row, --all, --aggregation-type, --data-state.

URL inspection

gsc inspect https://example.com/some-page -s sc-domain:example.com

Returns index status, coverage state, mobile usability, rich results, AMP status, canonical info.

Sitemaps

gsc sitemaps list -s sc-domain:example.com
gsc sitemaps submit https://example.com/sitemap.xml -s sc-domain:example.com

For AI agents

Tell your agent to run gsc docs — it prints a compact, LLM-optimized reference of every command. Or copy skills/gsc/SKILL.md into your project's .claude/skills/gsc/ directory (Claude Code) and AGENTS.md content into your agent instructions.

Environment variables agents can use: GSC_SITE (default property), GOOGLE_APPLICATION_CREDENTIALS (service account key), GSC_ACCESS_TOKEN (raw token), GSC_CONFIG_DIR (config location override).

Notes & limits

• Search analytics data lags 1–3 days behind; use --data-state all for fresher (non-final) data.
• URL Inspection API quota: 2000 requests/day and 600/minute per property.
• Tokens and config live in ~/.config/gsc-cli/ with 0600 permissions.

Development

npm install
npm test          # vitest
npm run typecheck # tsc --noEmit
npm run build     # tsup → dist/
node dist/index.js --help

See CONTRIBUTING.md. Licensed under MIT.