main 08051aa

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)

  1. In Google Cloud, enable the Google Search Console API.
  2. Create an OAuth client of type Desktop app and download its JSON.
  3. 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 page is incompatible with byProperty.
  • metadata.first_incomplete_date / first_incomplete_hour mark 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.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 2

Tags 1

↑↓ moveenter openesc close