Skip to main content

gsc-cli

PyPI version Python versions License: MIT Ruff

A fast, scriptable Google Search Console CLI - pull Search Analytics, inspect URLs, and manage sitemaps straight from your terminal, with clean --format json output that pipes into any tool. It also powers a set of Claude Code SEO-analysis skills.

Built and maintained by SEO Consult, a Bulgarian SEO агенция that lives in Search Console data.


Why gsc-cli

  • Everything as JSON. --format json on any command → feed rankings, CTR, and impressions into scripts, notebooks, or LLM prompts without scraping the UI.
  • Search Analytics done right. Query by query, page, country, device, or date, with repeatable AND-combined --filter expressions.
  • URL Inspection & sitemaps. Check index coverage for any URL and list/submit/ delete sitemaps.
  • Multi-profile auth. OAuth2 and service accounts, with per-site auto-detection - juggle many client properties from one config.
  • Table / CSV / JSON output for humans and machines alike.
  • The data the API leaves out. Google Lens / Circle to Search traffic (Web: multimodal) and the Generative AI report (AI Overviews + AI Mode) exist only as UI exports. gsc multimodal and gsc genai parse those exports and join them with API numbers for the same dates.

Install

pip install gsc-cli          # from PyPI
# or, for local development:
uv sync                      # create venv + install + register the `gsc` binary

Quick start

export GSC_CLIENT_SECRETS=/path/to/client_secrets.json   # from Google Cloud Console
gsc auth login                                           # OAuth2 browser flow
gsc sites list                                           # confirm access

# Top queries for the last 28 days, as JSON:
gsc --format json query https://www.example.com/ \
    --start-date 2026-01-01 --end-date 2026-01-28 --dimensions query

--format is global and precedes the subcommand (gsc --format json query ...). Filters use 'dimension operator expression', e.g. --filter 'query contains running shoes'.

Commands

Command What it does
gsc auth login, add-profile, list/remove-profile, status
gsc sites List and inspect verified properties
gsc query Search Analytics (clicks, impressions, CTR, position)
gsc inspect URL Inspection API - index/coverage verdict for a URL
gsc sitemaps list, get, submit, delete
gsc multimodal Parse a Web: multimodal export; --compare adds the camera share per page
gsc genai Parse a Generative AI report export; --compare adds the AI lift index per page

Run gsc --help or gsc <command> --help for the full flag reference.

AI Overviews and AI Mode by page

The Generative AI report in Search Console shows how often each page appeared inside AI Overviews and AI Mode. The API does not return it, so export it from the UI (Performance -> Generative AI -> Export -> Download CSV) and run:

gsc genai https://www.example.com/ export.zip --compare     --start-date 2026-06-22 --end-date 2026-09-21

For every page you get its AI impressions next to its organic clicks, impressions and average position, plus ai_lift: the page's share of AI impressions divided by its share of organic impressions. Above 1, AI uses the page more than its organic weight would suggest. Pages with fewer than 100 AI or 1,000 organic impressions are marked qualified: false, because small numbers give silly ratios.

Add --bands to see how AI impressions split across position bands (1-3, 4-10, 11-20, 21+). On the sites we have checked so far, most AI visibility sits on pages ranking 4-10, not in the top 3. Informational pages score high lift. Stock, deals and dealer-locator pages score close to zero, because Google rarely shows an AI answer for those searches.

--by date gives the daily series. Put it next to gsc query --dimensions date: if the AI-to-organic ratio suddenly collapses, check whether Googlebot can still reach the site. On one site, a firewall block cut organic impressions by 42% and AI impressions by 93%.

Some skill files mention companion skills (for example ai-visibility-tracking) from a larger private setup. They are optional; the gsc-* skills work on their own.

Use with Claude Code

gsc-cli is the backend for a suite of Claude Code SEO skills (performance overviews, cannibalization detection, quick-win opportunities, period compares, indexing audits). The skills shell out to gsc --format json and reason over the output. They ship as a Claude Code plugin in plugins/gsc-cli:

/plugin marketplace add seoconsultbg/gsc-cli
/plugin install gsc-cli@seoconsult

The plugin needs the gsc command on your PATH (uv tool install gsc-cli or pipx install gsc-cli). See CLAUDE.md for the architecture.

Configuration

Profiles live in ~/.config/gsc/config.yaml (override with GSC_CONFIG_DIR). A command resolves its profile by precedence: explicit --profile/$GSC_PROFILE → the profile whose sites list contains the target URL → default. Full details in CLAUDE.md.

Troubleshooting

  • invalid_grant / "Error refreshing OAuth token" about a week after login. Your OAuth consent screen is External and still in "Testing", and Google expires those refresh tokens after 7 days. Publish the app (Google Cloud Console > OAuth consent screen > Publish app) and run gsc auth login again.
  • Old logins stop working after many re-logins. Google keeps at most 100 refresh tokens per account per OAuth client and revokes the oldest without warning.
  • Service account works but gsc sites list is empty. Add the service account's client_email as a user on each Search Console property.

Contributing

Issues and PRs welcome. Lint/format with ruff (line-length 100):

uv run ruff check .
uv run pytest

License

MIT - © 2026 SEO Consult.


Maintained by the team at SEO Consult. If gsc-cli saves you time, a ⭐ on GitHub helps others find it.

Metadata

Release files for gsc-cli 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gsc-cli 0.2.1
File Size Uploaded Provenance Actions
gsc_cli-0.2.1.tar.gz 119.6 kB Without provenance Details for gsc_cli-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gsc-cli 0.2.1
File Interpreter ABI Platform Actions
gsc_cli-0.2.1-py3-none-any.whl Python 3 none any Details for gsc_cli-0.2.1-py3-none-any.whl

Total release size: 145.5 kB

Release files / gsc_cli-0.2.1.tar.gz

Download URL gsc_cli-0.2.1.tar.gz
Size 119.6 kB
Tags Source
SHA-256 checksum
How to use checksums
db67f1ea41cd136d79c671d0a44f4b9edd146acb3ffc2dee5a5cfad2f6a3b3f6
BLAKE2b-256 checksum
How to use checksums
acfe430745fc8b9d96fa86ec59b513780c0102c5e724e846addfd63dc61d1b91
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / gsc_cli-0.2.1-py3-none-any.whl

Download URL gsc_cli-0.2.1-py3-none-any.whl
Size 25.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2108d9bc08c390539e1f799b314a1d63f09b544e84dc1dbd9031e0dff3a6503b
BLAKE2b-256 checksum
How to use checksums
ab4d04b1be1e3514a7d996125a9509a48d73a4779e98cf3cb8a1d22effb72e58
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for gsc-cli 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page