Skillget

google-search-console-cli

agent
Security Audit
Fail
Health Pass
  • License — License: Apache-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 22 GitHub stars
Code Fail
  • rimraf — Recursive directory removal in pnpm-lock.yaml
  • network request — Outbound network request in pnpm-lock.yaml
  • os.homedir — User home directory access in src/auth.ts
  • process.env — Environment variable access in src/auth.ts
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Google Search Console CLI and skills for AI agents (and humans)

README.md

google-search-console-cli

Google Search Console CLI & Skills for AI agents (and humans). Analyze search performance by query, page, country, and device, inspect URL index status, manage sitemaps, and more.

Works with: OpenClaw, Claude Code, Cursor, Codex, and any agent that can run shell commands.

Installation

Tell your AI agent (e.g. OpenClaw):

Install this CLI and skills from https://github.com/Bin-Huang/google-search-console-cli

Or install manually:

npm install -g google-search-console-cli

# Add skills for AI agents (Claude Code, Cursor, Codex, etc.)
npx skills add Bin-Huang/google-search-console-cli

Or run directly: npx google-search-console-cli --help

For development:

pnpm install
pnpm build

How it works

Built on Google's official APIs. Handles service account authentication and request signing. Every command outputs structured JSON to stdout, ready for agents to parse without extra processing.

Core APIs covered:

Under the hood it uses the official Node.js client library googleapis. All API responses are passed through as JSON.

Setup

Step 1: Enable the Search Console API

Go to the Google Cloud Console API Library and enable the Google Search Console API for your project. If you don't have a project yet, create one first.

Step 2: Create a Service Account

  1. Go to IAM & Admin > Service Accounts in the same project.
  2. Click Create Service Account, give it a name (e.g. search-console-reader), and click Done.
  3. Click on the newly created Service Account, go to the Keys tab.
  4. Click Add Key > Create new key > JSON, and download the key file.

Step 3: Place the credentials file

Choose one of these options:

# Option A: Default path (recommended)
mkdir -p ~/.config/google-search-console-cli
cp ~/Downloads/your-key-file.json ~/.config/google-search-console-cli/credentials.json

# Option B: Environment variable
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your-key-file.json"

# Option C: Pass per command
google-search-console-cli sites --credentials /path/to/your-key-file.json

Credentials are resolved in this order:

  1. --credentials <path> flag
  2. GOOGLE_APPLICATION_CREDENTIALS env var
  3. ~/.config/google-search-console-cli/credentials.json (auto-detected)
  4. gcloud Application Default Credentials

Step 4: Grant access in Search Console

The Service Account needs permission to access your sites in Search Console. This must be done per site.

  1. Open Google Search Console.
  2. Select a site you want to grant access to.
  3. Go to Settings (bottom-left) > Users and permissions.
  4. Click Add user.
  5. Enter the Service Account email (find it in your key file's client_email field, e.g. [email protected]).
  6. Choose a permission level:
    • Restricted (read-only): can use sites, site, query, sitemaps, sitemap, inspect, inspect-batch
    • Full: can also use site-add, site-remove, sitemap-submit, sitemap-delete
  7. Click Add.

Repeat for each site you want to access. There is no global "add to all sites" option in Search Console.

Troubleshooting "Email not found":

  • Paste the client_email value (it ends in .iam.gserviceaccount.com), not client_id or an OAuth client ID.
  • Make sure the Service Account is enabled in the Cloud Console.
  • A newly created Service Account can take a few minutes before Search Console accepts it. Wait, then try again.
  • Choose Full or Restricted. Do not choose Owner.
  • If it still fails, use your own Google account instead (see below).

Alternative: gcloud ADC (for local development)

If you prefer not to use a Service Account, you can authenticate with your own Google account:

gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform"

# Bill API usage to the project where you enabled the Search Console API (Step 1)
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

gcloud requires the cloud-platform scope. For write commands (site-add, sitemap-submit, etc.), use https://www.googleapis.com/auth/webmasters instead of webmasters.readonly. The CLI uses these credentials only when no key file is found (see the resolution order in Step 3), so remove or rename ~/.config/google-search-console-cli/credentials.json if it exists.

This uses your personal Google account's Search Console access. Good for local development, not recommended for automation.

Usage

All commands output pretty-printed JSON by default. Use --format compact for compact single-line JSON.

Site URLs follow the Search Console format:

  • URL-prefix property: https://www.example.com/ (must include trailing slash)
  • Domain property: sc-domain:example.com

query

Query search analytics data with filters and dimensions.

# Basic query: top queries for the last 30 days
google-search-console-cli query https://www.example.com/ \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --dimensions query

# Top pages by country
google-search-console-cli query sc-domain:example.com \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --dimensions page,country \
  --row-limit 100

# With dimension filters
google-search-console-cli query https://www.example.com/ \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --dimensions query \
  --dimension-filter '[{"groupType":"and","filters":[{"dimension":"country","operator":"equals","expression":"USA"}]}]'

# Image search results
google-search-console-cli query https://www.example.com/ \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --dimensions query \
  --type image

# Include fresh (unfinalized) data
google-search-console-cli query https://www.example.com/ \
  --start-date 2025-01-01 \
  --end-date 2025-01-31 \
  --dimensions date \
  --data-state all

Available dimensions: date, query, page, country, device, searchAppearance, hour

Available types: web (default), image, video, news, discover, googleNews

Additional options:

  • --row-limit <n> -- Max rows, 1-25000 (default 1000)
  • --start-row <n> -- Starting row offset (default 0)
  • --data-state <state> -- Data freshness: all, final, hourly_all
  • --aggregation-type <type> -- Aggregation type: auto, byPage, byProperty, byNewsShowcasePanel
  • --all -- Fetch all rows with auto-pagination (mutually exclusive with --start-row)

sites

List all sites in your Search Console account.

google-search-console-cli sites

site

Get information about a specific site.

google-search-console-cli site https://www.example.com/
google-search-console-cli site sc-domain:example.com

site-add

Add a site to Search Console. Requires Full permission.

google-search-console-cli site-add https://www.example.com/

site-remove

Remove a site from Search Console. Requires Full permission.

google-search-console-cli site-remove https://www.example.com/

sitemaps

List sitemaps for a site.

google-search-console-cli sitemaps https://www.example.com/

# Only list sitemaps under a specific sitemap index
google-search-console-cli sitemaps https://www.example.com/ \
  --sitemap-index https://www.example.com/sitemap-index.xml

sitemap

Get information about a specific sitemap.

google-search-console-cli sitemap https://www.example.com/ https://www.example.com/sitemap.xml

sitemap-submit

Submit a sitemap for a site. Requires Full permission.

google-search-console-cli sitemap-submit https://www.example.com/ https://www.example.com/sitemap.xml

sitemap-delete

Delete a sitemap from a site. Requires Full permission.

google-search-console-cli sitemap-delete https://www.example.com/ https://www.example.com/sitemap.xml

inspect

Inspect a URL's index status in Google.

google-search-console-cli inspect https://www.example.com/ https://www.example.com/my-page

# With a specific language for messages
google-search-console-cli inspect https://www.example.com/ https://www.example.com/my-page --language zh-CN

inspect-batch

Batch inspect multiple URLs' index status in a single command.

# From a file (one URL per line)
google-search-console-cli inspect-batch https://www.example.com/ --file urls.txt

# From stdin
cat urls.txt | google-search-console-cli inspect-batch https://www.example.com/

# With compact format (NDJSON, streams results as they complete)
cat urls.txt | google-search-console-cli inspect-batch https://www.example.com/ --format compact

Options:

  • --file <path> -- File with URLs (one per line); reads stdin if omitted
  • --language <code> -- Language code for messages (default: en-US)

Progress is written to stderr. With --format compact, each result is streamed as NDJSON (one JSON object per line) as it completes. With the default format, all results are collected and output as a JSON array. Per-URL errors are captured in the output (with error and, when available, code) without stopping the batch. If any URL fails, the command still prints all results, then writes a summary error to stderr and exits with code 1.

Error output

Errors are written to stderr as JSON with an error field. For Google API errors, code and details are included when available:

{"error": "Permission denied", "code": 403}

Related

License

Apache-2.0

Reviews (0)

No results found