gsc-cli
Go client library and CLI for the Google Search Console API: Search Analytics, sites, sitemaps, and URL Inspection.
go install bnema.dev/gsc-cli/cmd/gsc@latest
Setup (once)
- In Google Cloud, enable the Google Search Console API.
- Create an OAuth client of type Desktop app and download its JSON.
- Log in:
gsc auth login --client-secret ~/Downloads/client_secret_XXX.json
gsc auth login prints a short local URL (http://127.0.0.1:PORT/login, which redirects to Google consent) and returns. Open it in a browser where
your Google account is signed in; a background listener on 127.0.0.1
receives the callback and stores the token. Check with gsc auth status; it
also shows why the last background login failed (for example a timeout).
The URL stays valid for 10 minutes (--timeout). Use --wait to block instead.
Files live in $XDG_CONFIG_HOME/gsc-cli/ (mode 0600). Tokens refresh
automatically. Login defaults to --scope readonly (webmasters.readonly).
Use gsc auth login --scope full (webmasters) for sites add/delete and
sitemaps submit/delete. The granted scope is stored privately; older logins
without scope metadata count as read-only. gsc auth status --format json
includes scope (readonly or full). Refreshing tokens preserves scope.
Commands
gsc sites # same as sites list
gsc sites get --site sc-domain:example.com
gsc sites add --site sc-domain:example.com # full scope
gsc sites delete --site sc-domain:example.com --yes
gsc sitemaps list --site sc-domain:example.com # optional --index URL
gsc sitemaps get --site sc-domain:example.com --feed https://example.com/sitemap.xml
gsc sitemaps submit --site sc-domain:example.com --feed https://example.com/sitemap.xml
gsc sitemaps delete --site sc-domain:example.com --feed https://example.com/sitemap.xml --yes
gsc inspect --site sc-domain:example.com --url https://example.com/page --lang en-US
gsc dates --site sc-domain:example.com # which days have data
gsc query --site sc-domain:example.com --dim query --limit 10
gsc query --site https://www.example.com/ --dim page,device \
--filter 'country=fra' --filter 'page contains /blog' --all --format json
gsc auth status --format json
gsc auth logout
All data commands accept --format table|json|csv. New resource commands use
API field names; sitemap lists have one row per sitemap, and nested table/CSV
values are JSON cells. Successful writes emit
{} in JSON. Deletions require --yes; write-scope and confirmation checks run
before HTTP client creation. Data goes to stdout, errors to stderr.
| Flag | Values |
|---|---|
--site |
sc-domain:example.com or https://www.example.com/ |
--start, --end |
YYYY-MM-DD, Pacific Time, inclusive. Default: 28 days ending 3 days ago |
--dim |
query,page,country,device,searchAppearance,date,hour |
--filter |
repeatable, ANDed: dim=expr or dim op expr |
| filter ops | equals, notEquals, contains, notContains, includingRegex, excludingRegex (RE2) |
--type |
web (default), image, video, news, discover, googleNews |
--agg |
auto, byPage, byProperty, byNewsShowcasePanel |
--data-state |
final (default), all (fresh data), hourly_all |
--limit, --start-row |
1–25000 (default 1000), offset |
--all, --max |
page through all rows in 25000 batches, optional cap |
--format |
table, json, csv |
Filter dimensions: country uses ISO 3166-1 alpha-3 (fra, usa), device
uses DESKTOP, MOBILE, TABLET.
Library
hc, _ := store.Session(ctx, false) // or any oauth2 *http.Client
c := gsc.New(hc)
resp, err := c.QueryAll(ctx, "sc-domain:example.com", gsc.QueryRequest{
StartDate: "2026-01-01", EndDate: "2026-01-31",
Dimensions: []gsc.Dimension{gsc.DimQuery},
DimensionFilterGroups: gsc.AndGroup(gsc.Filter{Dimension: gsc.DimDevice, Expression: "MOBILE"}),
}, 0)
API notes
- Rows are sorted by clicks (descending), or by date when grouped by
date. - The API returns top rows, not every row; days without data are omitted.
- Grouping or filtering by
pageis incompatible withbyProperty. metadata.first_incomplete_date/first_incomplete_hourmark fresh data that may still change.
Resources and quotas
The library exposes GetSite, AddSite, DeleteSite, ListSitemaps,
GetSitemap, SubmitSitemap, DeleteSitemap, and InspectURL alongside
Sites, Query, and QueryAll. Configure test endpoints with
WithBaseURL and WithInspectionBaseURL. URL Inspection uses a separate
https://searchconsole.googleapis.com/v1 base and returns the indexed version,
not a live test. Optional result sections can be absent. Deprecated mobile
usability results and sitemap indexed counts remain modeled. Sitemap int64
counters are plain strings; timestamps and enum values retain API strings.
Quotas include short-term
and long-term load limits, as well as request limits. Grouping by both page
and query, and long date ranges, consume more load. On a quota error, wait
about 15 minutes and simplify the query; daily limits may require longer.
URL Inspection has separate per-site/per-project quotas (including 2,000
inspections per site per day). APIError.IsQuotaExceeded() recognizes HTTP 429,
RESOURCE_EXHAUSTED, and quota messages; the CLI adds recovery guidance.
License
MIT, see LICENSE.