gsc-cli
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 jsonon 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, ordate, with repeatable AND-combined--filterexpressions. - 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 multimodalandgsc genaiparse 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 rungsc auth loginagain.- 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 listis empty. Add the service account'sclient_emailas 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.