gsc

name	gsc
description	Work with Google Search Console via the gsc CLI (searchconsole-cli). Use when the user asks about search performance, Google rankings, clicks/impressions, indexing status, URL inspection, or sitemaps for their site.

Google Search Console via gsc

Use the gsc CLI for all Search Console work. If not installed, use npx searchconsole-cli ….

Workflow

1. gsc auth status — if "method": "none", stop and ask the user to run gsc auth login (zero setup, browser approval required) or provide a service account key (GOOGLE_APPLICATION_CREDENTIALS). Never attempt the login yourself.
2. gsc sites list — get the exact property string. Never guess between sc-domain:example.com and https://example.com/.
3. Run the query/inspection the user needs (see below).
4. All output is JSON on stdout; errors are JSON on stderr with a hint field explaining the fix.

Commands

gsc query -s <property> --dimensions query --row-limit 25        # top search queries
gsc query -s <property> --dimensions page --row-limit 25         # top pages
gsc query -s <property> --dimensions date --days 90              # traffic over time
gsc query -s <property> --dimensions page,query --filter "query contains <topic>" --all
gsc query -s <property> --type discover --dimensions page        # Discover traffic
gsc inspect <url> -s <property>                                  # indexing status
gsc sitemaps list -s <property>                                  # sitemaps + errors
gsc sitemaps submit <sitemap-url> -s <property>
gsc sites list | gsc sites get/add/remove <property>
gsc docs                                                         # full reference

Query options: --start-date/--end-date (YYYY-MM-DD), --days N (default 28, ends yesterday), --dimensions query,page,country,device,date,searchAppearance, --type web|image|video|news|discover|googleNews, repeatable --filter "dim op expr" (contains, equals, notContains, notEquals, includingRegex, excludingRegex), --row-limit (max 25000), --all (auto-paginate), --data-state final|all|hourly_all.

Interpretation

• Rows: clicks, impressions, ctr (0–1), position (avg, lower = better); keys follows dimension order.
• Data lags 1–3 days — empty recent dates are normal, --data-state all includes fresh data.
• inspect headline: inspectionResult.indexStatusResult.coverageState.
• URL inspection quota: 2000/day per property — never loop over large URL lists.