google-search-console-cli 0.1.0

CLI for Google Search Console

google-search-console-cli

CLI for Google Search Console using the official Google API Python client.

Highlights

• Native OAuth login: no mandatory gcloud setup
• pipx-friendly install (gsc available globally)
• Site operations: list/get/add
• Analytics queries by date/query/page with Search Console filters
• Output formats: table, json, csv
• Diagnostics: gsc doctor

Install (Recommended)

Install with pipx so gsc is available on your PATH:

pipx install google-search-console-cli

Install From Source

If you cloned this repository and want to run from source, use one of these options.

Option 1: Local virtualenv (best for development)

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Fish shell activation:

. .venv/bin/activate.fish

Then run:

gsc --help

Option 2: Install from source with pipx (best for day-to-day CLI usage)

pipx install -e /absolute/path/to/google-search-console-cli

OAuth Setup (Recommended)

Create a Google OAuth client of type Desktop app, then run:

gsc auth login --client-secret /absolute/path/to/client_secret.json

Verify:

gsc auth whoami
gsc doctor

Optional: Set Default Site

gsc config set default-site sc-domain:example.com
gsc config get default-site

After this, you can omit --site in commands that need a property.

Usage

Sites

gsc site list
gsc site get --site sc-domain:example.com
gsc site add --site sc-domain:example.com

Analytics

gsc analytics query \
  --site sc-domain:example.com \
  --start-date 2026-01-01 \
  --end-date 2026-01-31 \
  --dimension date \
  --dimension query \
  --filter query:contains:brand \
  --filter device:equals:MOBILE

Save as CSV:

gsc analytics query \
  --site sc-domain:example.com \
  --start-date 2026-01-01 \
  --end-date 2026-01-31 \
  --dimension page \
  --output csv \
  --csv-path ./analytics.csv

Filter Syntax

Use repeatable filters in this format:

dimension:operator:expression

Supported filter dimensions:

• country
• device
• page
• query
• searchAppearance

Supported operators:

• contains
• equals
• notContains
• notEquals
• includingRegex
• excludingRegex

Convenience Script (Repo Local)

If you cloned this repo and want one command setup:

./scripts/setup.sh /absolute/path/to/client_secret.json

Credentials and Config Paths

By default:

• Credentials: ~/.config/gsc-cli/credentials.json
• Config: ~/.config/gsc-cli/config.json

Override with env vars:

• GSC_CREDENTIALS_FILE
• GSC_APP_CONFIG_FILE
• GSC_CONFIG_DIR

ADC Fallback (Optional)

If you prefer ADC via gcloud, the CLI still supports it:

gcloud auth application-default login \
  --client-id-file=/absolute/path/to/client_secret.json \
  --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/webmasters

Notes

• Use Search Console property formats like sc-domain:example.com or URL-prefix properties.
• site add requires write scope (webmasters).
• analytics query --aggregation-type byProperty cannot be combined with page grouping/filtering.