Using gsc.

Getting started

SearchProbe is a single Go binary named gsc. Install it from a checkout of the repository with Go 1.22 or newer:

git clone https://github.com/morgancrozier/searchprobe \
  && cd searchprobe && go install ./cmd/gsc

The binary lands in $(go env GOBIN), or $(go env GOPATH)/bin when GOBIN is unset. Make sure that directory is on your PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Then confirm the shell resolves the SearchProbe binary. Some systems already have another gsc executable (Ghostscript installs one); SearchProbe never overwrites it and relies on normal PATH precedence.

command -v gsc
gsc --version

Homebrew packaging and tagged releases are planned. Until then, go install github.com/morgancrozier/searchprobe/cmd/gsc@latest does not work; use the checkout install above. To uninstall, remove the binary and run gsc auth logout first if you no longer want the stored credentials.

Commands

Every command is read-only. Add --json to any of them for the machine-readable envelope, and --help for the full flag reference.

Search Analytics

gsc performance takes --site with a property identifier exactly as printed by gsc sites, plus --days N or --start and --end. Dimensions are Google’s own: query, page, country, device, date, searchAppearance, and hour. Filters use Google’s dimension and operator names and are ANDed when repeated:

gsc performance \
  --site sc-domain:example.com \
  --start 2026-08-01 --end 2026-08-31 \
  --dimensions page \
  --filter "page contains /blog/" \
  --all --json

--limit caps one request at up to 25,000 rows and --start-row offsets it. --all pages through every row the API exposes for the query. --dimensions "" returns one row of property-level totals, which summing query or page rows never reproduces.

Comparison

gsc compare runs the same query over two windows and joins rows by dimension values. --previous uses the immediately preceding window of equal length; the explicit --compare-start and --compare-end flags give another window. Deltas are current minus previous. Position is lower-is-better, so a negative position delta is an improvement. --sort and --asc control ordering.

URL inspection

gsc inspect <url> --site <property> returns Google’s indexed version of a URL: verdict, coverage, canonicals, last crawl, and rich results. Pass --urls-file to inspect a list sequentially.

Authentication

gsc requests only the read-only Search Console scope, https://www.googleapis.com/auth/webmasters.readonly, and enforces it at the OAuth layer. Sign-in uses Google’s desktop-app flow: PKCE with S256 and a loopback callback on a random local port. Credentials are stored in ~/.config/gsc/credentials.json with mode 0600 and refreshed automatically. Set GSC_CONFIG_DIR to use a different directory.

Today the CLI signs in with a Desktop OAuth client from your own Google Cloud project. Create a project, enable the Google Search Console API, configure the consent screen with yourself as a test user, create an OAuth client of type “Desktop app”, download its JSON, and store it outside any repository. The repository README walks through each step. Then:

gsc auth login --client-file ~/.config/gsc/client.json

Refresh tokens issued to a Google Cloud app in Testing status expire after seven days; run gsc auth login again when that happens. gsc auth status reports the stored state without a network call, and gsc auth logout revokes the grant and removes the local file.

A shared, verified SearchProbe OAuth client is planned so that gsc auth login works without any Google Cloud setup. Bring-your-own credentials will remain available for isolated quota or organisational control.

JSON output

JSON mode is an API surface, not debug output. Every --json invocation prints one envelope to stdout:

{ "ok": true, "data": {}, "meta": {}, "warnings": [] }

or, on failure,

{ "ok": false, "error": { "code": "AUTH_REQUIRED", "message": "...", "action": "..." } }

Field names are stable, values are typed, and human diagnostics go to stderr. For Search Analytics, meta records the exact startDate, endDate, timezone (always America/Los_Angeles), searchType, dataState, dimensions, and filters used, along with pagination accounting and sourceMayBePartial, which is always true because Google returns top rows only. Warnings are structured and reserved for conditions that change how a result should be read.

API limitations

SearchProbe uses the official Search Console API and inherits its limits. It surfaces them in metadata and warnings rather than hiding them.

• Search Analytics returns top rows and does not guarantee that every underlying row is exposed.
• One Search Analytics response is limited to 25,000 rows; pagination uses startRow.
• Search Analytics dates are Pacific Time calendar days.
• Finalized data typically lags two or three days, so the most recent days are absent unless you request preliminary data with --data-state all.
• Expensive combinations such as page plus query over long ranges consume more load quota.
• URL Inspection returns Google’s indexed version; it cannot run the live URL test.
• The API does not expose every Search Console report, and it does not offer the “Request indexing” action.

See GSC_API.md in the repository for the full notes, and Google’s own usage limits.

More

• README — full setup, verification, and status
• ARCHITECTURE.md — OAuth flow, security, and the field-level JSON contract
• ROADMAP.md — what is done and what is deferred
• Privacy and terms