gsc

README

gsc

Agent-friendly, read-only Go CLI for the official Google Search Console APIs. gsc reports how verified websites perform in Google Search; it does not scrape search results or create a replacement API.

gsc ──OAuth 2.0──► Google Search Console API
 │                       │
 └─ stable JSON ◄────────┴─ clicks, impressions, CTR, position,
                            queries, pages, sitemaps, index status

Search Console data covers Google organic-search discovery before a visitor enters the website. It is not complete website traffic or product analytics: combine it with OpenPanel or GA4 for sessions, behavior, funnels, and conversions. It also cannot report competitors' private Search Console data; use a SERP data provider for competitor research.

Official references: Search Console API, Search Analytics query, and URL Inspection API.

Install

Supported release targets: macOS Apple Silicon, macOS Intel, and Linux x86_64.

curl -fsSL https://raw.githubusercontent.com/radjathaher/gsc/main/scripts/install.sh | bash

Install a specific release or destination:

GSC_VERSION=v0.1.0 BIN_DIR="$HOME/bin" \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/radjathaher/gsc/main/scripts/install.sh)"

The installer verifies the archive against the release's SHA256SUMS file before installing gsc.

Build from source:

git clone https://github.com/radjathaher/gsc.git
cd gsc
go build -o gsc .
./gsc --version

Google setup

Two independent permissions are required:

Website control                         API identity
──────────────                          ────────────
DNS TXT or another verification         OAuth user or service account
        │                                      │
        ▼                                      ▼
Search Console property ──grants access──► credential used by gsc

OAuth identifies the caller; it does not prove website ownership. Verify the website in Search Console first. A Domain property such as sc-domain:example.com uses DNS verification and covers protocols and subdomains. Keep its verification record in DNS. See Google's property verification guide.

For durable automation:

1. Create or select a Google Cloud project.
2. Enable the Google Search Console API.
3. Create a service account and download its JSON credential.
4. Add the service account's email as a user on each Search Console property.
5. Expose the credential through one of the sources below.

An authorized-user OAuth credential with a refresh token also works. The caller still needs access to each requested property. gsc requests only https://www.googleapis.com/auth/webmasters.readonly; v0.1.0 has no mutating commands. See Google's Search Console authorization guide.

Credentials

Credential resolution, highest precedence first:

1. GSC_CREDENTIALS_JSON: credential JSON itself.
2. GOOGLE_APPLICATION_CREDENTIALS: path to a credential JSON file.
3. /run/secrets/GSC_CREDENTIALS_JSON: fleet secret file containing credential JSON.

Examples:

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gsc/credentials.json"

# Fleet/CI alternative: JSON value injected by the secret manager.
export GSC_CREDENTIALS_JSON='{"type":"service_account",...}'

Never commit credentials. A credential grants only an identity; Search Console separately checks that identity's property permissions.

Commands

List accessible properties:

gsc sites list

Run a Search Analytics query. Repeat --dimension to group rows:

gsc performance query \
  --site sc-domain:example.com \
  --start-date 2026-06-01 \
  --end-date 2026-06-30 \
  --dimension query \
  --dimension page

Common 28-day reports:

gsc keywords --site sc-domain:example.com --days 28
gsc pages --site sc-domain:example.com --days 28

Inspect a URL's Google index status:

gsc inspect \
  --site sc-domain:example.com \
  --url https://example.com/pricing

List submitted sitemaps:

gsc sitemaps list --site sc-domain:example.com

Use gsc --help or <command> --help for the full flag surface.

Output and data meaning

• Successful commands emit JSON to stdout; diagnostics and errors go to stderr.
• Search Analytics rows can include clicks, impressions, ctr, and average position, grouped by requested dimensions.
• query means the Google search phrase; page means the landing URL shown in Search.
• Search Console reports aggregated Google Search data. It may return top rows rather than every possible row and is subject to Google's data limits.
• URL inspection reports the indexed version known to Google, not a guaranteed live crawl result.

Releases

Tags matching v* run formatting, vet, race-enabled tests, and builds before publishing exactly three archives and their checksums:

gsc-<version>-darwin-aarch64.tar.gz
gsc-<version>-darwin-x86_64.tar.gz
gsc-<version>-linux-x86_64.tar.gz
SHA256SUMS

Each archive contains the gsc binary at its root. These assets are also the package source consumed by the alif/nix fleet configuration.