gsc

README

gsc

Minimal CLI for the Google Search Console API. One binary, service-account auth, raw API JSON on stdout. Built for scripting: pipe to jq, call from CI, wrap in agent skills.

The API has four resource groups and this tool covers all of them: sites, sitemaps, search analytics, and URL inspection. Nothing else — no config files, no interactive login, no output formats to learn.

Install

go install github.com/jparavisini/gsc@latest

Or grab a prebuilt binary for macOS, Linux, or Windows from releases.

Auth

Service account only. Resolved in order:

1. GSC_CREDENTIALS_JSON — inline service account JSON (for CI secrets)
2. GSC_CREDENTIALS — path to a service account JSON file
3. GOOGLE_APPLICATION_CREDENTIALS — path to a service account JSON file

One-time setup:

1. In Google Cloud console, enable the Search Console API on a project and create a service account with a JSON key. No IAM roles needed.
2. In Search Console, add the service account's email as a user on each property. Full permission is required for sitemaps submit/delete; Restricted is enough for reads.

Usage

Properties are written exactly as Search Console shows them: https://example.com/ (URL-prefix) or sc-domain:example.com (domain).

gsc sites list

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

# Search analytics: 16 months of history, 25k rows max per call
gsc query sc-domain:example.com --start 2026-06-01 --end 2026-06-30 \
  --dimensions query,page --limit 5000 \
  --filter page:contains:/blog

# Index status for one URL (quota: 2000/day, 600/min per property)
gsc inspect sc-domain:example.com https://example.com/services/

Output is the unmodified API response. Errors go to stderr with exit code 1; sitemaps submit/delete print a confirmation to stderr and nothing to stdout.

# top queries by clicks
gsc query sc-domain:example.com --start 2026-06-01 --end 2026-06-30 \
  --dimensions query | jq -r '.rows[] | "\(.clicks)\t\(.keys[0])"' | sort -rn | head

# is this page indexed?
gsc inspect sc-domain:example.com https://example.com/pricing/ \
  | jq -r .inspectionResult.indexStatusResult.coverageState

CI example (GitHub Actions)

- name: Submit sitemap to Search Console
  env:
    GSC_CREDENTIALS_JSON: ${{ secrets.GSC_SERVICE_ACCOUNT_JSON }}
  run: gsc sitemaps submit "sc-domain:${SITE_DOMAIN}" "https://${SITE_DOMAIN}/sitemap.xml"

Not included

• Request indexing. The GSC UI button has no API. Google's Indexing API only covers JobPosting/BroadcastEvent pages and is enforced; this tool doesn't touch it.
• Core Web Vitals, crawl stats, links report, manual actions — not exposed by the API.

License

MIT

Documentation

Overview

gsc is a minimal CLI for the Google Search Console API.

Authentication is a service account only. The service account's email must be added as a user on each Search Console property (Full permission is required for sitemap submit/delete).

Credentials are resolved in order:

1. GSC_CREDENTIALS_JSON — inline service account JSON (for CI secrets)
2. GSC_CREDENTIALS — path to a service account JSON file
3. GOOGLE_APPLICATION_CREDENTIALS — path to a service account JSON file

All commands print the raw API JSON response to stdout. Errors go to stderr with a non-zero exit.