gsc-cli is a small, read-only Go CLI for Google Search Console.
It is intentionally narrow:
- service-account only
- no browser OAuth
- no token persistence
- no write operations
- no MCP server in v1
gsc-cli sites listgsc-cli analytics querygsc-cli analytics top-pagesgsc-cli analytics top-queriesgsc-cli help <topic>gsc-cli report overviewgsc-cli report comparegsc-cli sitemaps listgsc-cli inspect url
- Create a dedicated Google Cloud project for Search Console access.
- Enable the Search Console API.
- Create a dedicated service account.
- Download the service account JSON key.
- Add the service account email as a user on the Search Console property you want to query.
Recommended property format:
sc-domain:example.com
Keep the service-account JSON key out of the repository. The project .gitignore
already excludes common local key filenames such as service-account*.json.
go build ./...Install directly from the module:
go install github.com/benedict2310/gsc-cli/cmd/gsc-cli@latestOr build and install locally to the Homebrew prefix bin directory:
go build -o ./gsc-cli ./cmd/gsc-cli
install -m 755 ./gsc-cli "$(brew --prefix)/bin/gsc-cli"Verify:
command -v gsc-cli
gsc-cli --helpIf you only know the property and credentials, start with:
gsc-cli report overview \
--credentials-file ./service-account.json \
--site sc-domain:example.com \
--output tableYou can pass credentials and site on the command line:
gsc-cli sites list \
--credentials-file ./service-account.jsongsc-cli analytics query \
--credentials-file ./service-account.json \
--site sc-domain:example.com \
--start 2026-03-01 \
--end 2026-03-14 \
--dimensions query,page \
--search-type web \
--output tablegsc-cli analytics top-pages \
--credentials-file ./service-account.json \
--site sc-domain:example.com \
--output tablegsc-cli analytics top-queries \
--credentials-file ./service-account.json \
--site sc-domain:example.com \
--output tablegsc-cli report overview \
--credentials-file ./service-account.json \
--site sc-domain:example.com \
--days 28 \
--limit 10 \
--output tablegsc-cli report compare \
--credentials-file ./service-account.json \
--site sc-domain:example.com \
--days 28 \
--dimension page \
--output tablegsc-cli help analytics querygsc-cli sitemaps list \
--credentials-file ./service-account.json \
--site sc-domain:example.comgsc-cli inspect url \
--credentials-file ./service-account.json \
--site sc-domain:example.com \
--url https://example.com/gsc-cli doctor \
--credentials-file ./service-account.json \
--site sc-domain:example.com \
--output tablegsc-cli version --output jsonYou can also use environment variables:
export GSC_CLI_CREDENTIALS_FILE=./service-account.json
export GSC_CLI_SITE_URL=sc-domain:example.comThen run:
gsc-cli analytics query --start 2026-03-01 --end 2026-03-14Supported output modes:
json(default)table
For top-pages, top-queries, and report overview:
--dayssupports7,28, or90- default is
28 - explicit
--startand--endtake precedence over--days
For report compare:
- compares the current period against the immediately preceding equal-length period
- supports
--dimension pageand--dimension query
go test ./...
go test -race ./...
go vet ./...