google-search-console-cli
Google Search Console data analysis and site management via google-search-console-cli. Use when the user wants to check search performance, analyze queries, inspect URL index status, manage sitemaps, or view site properties. Triggers: "Search Console", "search performance", "search queries", "GSC", "index status", "URL inspection", "sitemap", "search analytics", "impressions", "CTR", "search appearance".
Bin-Huang · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Bin-Huang/google-search-console-cli --skill google-search-console-cli技能说明
name: google-search-console-cli description: > Google Search Console data analysis and site management via google-search-console-cli. Use when the user wants to check search performance, analyze queries, inspect URL index status, manage sitemaps, or view site properties. Triggers: "Search Console", "search performance", "search queries", "GSC", "index status", "URL inspection", "sitemap", "search analytics", "impressions", "CTR", "search appearance".
Google Search Console CLI Skill
You have access to google-search-console-cli, a CLI for the Google Search Console API. Use it to query search analytics, inspect URL indexing, and manage sites and sitemaps.
Quick start
# Check if the CLI is available
google-search-console-cli --help
# List accessible sites
google-search-console-cli sites
If the CLI is not installed, install it:
npm install -g google-search-console-cli
Authentication
The CLI uses a Google service account. Credentials are resolved in this order:
--credentials <path>flag (per-command)GOOGLE_APPLICATION_CREDENTIALSenv var~/.config/google-search-console-cli/credentials.json(auto-detected)- gcloud Application Default Credentials
Before running any command, verify credentials are configured by running google-search-console-cli sites. If it fails with a credentials error, ask the user to set up authentication.
Site URL formats
Search Console uses two property types:
- URL-prefix property:
https://www.example.com/(must include trailing slash and protocol) - Domain property:
sc-domain:example.com(covers all protocols and subdomains)
Always use the exact format as registered in Search Console. The site URL is a positional argument for most commands.
Output format
All commands output pretty-printed JSON by default. Use --format compact for single-line JSON (useful for piping).
Commands
Search analytics query
The query command is the primary tool for search performance data.
google-search-console-cli query <siteUrl> --start-date <date> --end-date <date> [options]
Required:
--start-date <date>-- Start date (YYYY-MM-DD)--end-date <date>-- End date (YYYY-MM-DD)
Optional:
--dimensions <names>-- Comma-separated:date,query,page,country,device,searchAppearance,hour--type <type>-- Search type:web(default),image,video,news,discover,googleNews--dimension-filter <json>-- JSON array of dimension filter groups (see below)--aggregation-type <type>--auto,byPage,byProperty,byNewsShowcasePanel--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--all-- Fetch all rows with auto-pagination (mutually exclusive with--start-row)
Response fields per row:
keys-- Array of dimension values (in the order specified by--dimensions)clicks-- Number of clicksimpressions-- Number of impressionsctr-- Click-through rate (0.0 to 1.0)position-- Average position in search results
Auto-pagination with --all
When --all is specified, the CLI automatically paginates through all results (using 25000 rows per page) and returns the complete dataset. This is useful for exporting all data without manual pagination.
# Get ALL queries (auto-paginates through all pages)
google-search-console-cli query https://www.example.com/ \
--start-date 2026-02-16 \
--end-date 2026-03-17 \
--dimensions query \
--all
Note: --all and --start-row cannot be used together. When --all is used, --row-limit is ignored.
Sites management
# List all sites
google-search-console-cli sites
# Get info about a specific site
google-search-console-cli site <siteUrl>
# Add a site (requires Full permission)
google-search-console-cli site-add <siteUrl>
# Remove a site (requires Full permission)
google-search-console-cli site-remove <siteUrl>
Sitemaps management
# List sitemaps for a site
google-search-console-cli sitemaps <siteUrl>
# List sitemaps under a specific sitemap index
google-search-console-cli sitemaps <siteUrl> --sitemap-index <url>
# Get info about a specific sitemap
google-search-console-cli sitemap <siteUrl> <feedpath>
# Submit a sitemap (requires Full permission)
google-search-console-cli sitemap-submit <siteUrl> <feedpath>
# Delete a sitemap (requires Full permission)
google-search-console-cli sitemap-delete <siteUrl> <feedpath>
URL inspection
# Inspect a single URL's index status
google-search-console-cli inspect <siteUrl> <inspectionUrl>
# With a specific language for messages
google-search-console-cli inspect <siteUrl> <inspectionUrl> --language zh-CN
The --language option controls the language of the messages in the response (default: en-US).
The response includes: index status (indexing state, crawl time, robots.txt status, canonical URL), AMP analysis (if applicable), mobile usability, and rich results detection.
Batch URL inspection
Inspect multiple URLs 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: Inspecting 1/50: https://...
With --format compact, each result is streamed as NDJSON (one JSON object per line) as soon as it completes. With --format json (default), all results are collected