gsc-cli

Query Google Search Console from the terminal. Pull top queries, compare date ranges, export CSVs, and flag ranking drops.

Installation

# From source
go install ./cmd/gsc-cli

# Or build locally
make build
./bin/gsc-cli

Why gsc-cli and not gsc

Ghostscript ships a binary called gsc, and Homebrew installs it to /opt/homebrew/bin/gsc. On a machine with Ghostscript present that directory usually precedes $GOPATH/bin on PATH, so a bare gsc silently runs Ghostscript instead — no error, just the wrong tool. The binary is therefore named gsc-cli, which collides with nothing. Do not add a gsc alias: the failure it reintroduces is silent, and silent is the whole problem.

Setup

1. Create Google Cloud OAuth Credentials

1. Go to Google Cloud Console
2. Create a new project (or select existing)
3. Enable the Search Console API
4. Go to APIs & Services → Credentials
5. Click Create Credentials → OAuth client ID
6. Select Desktop app
7. Download the client_secret.json file

2. Authenticate

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

This opens your browser for Google OAuth consent. Tokens are stored securely in your OS keychain.

Usage

Top Queries

# Last 28 days, top 100 queries
gsc-cli queries

# Last 7 days
gsc-cli queries --days 7

# Custom date range
gsc-cli queries --start 2025-01-01 --end 2025-01-15

# Top 500 queries
gsc-cli queries --limit 500

# Filter by page pattern
gsc-cli queries --filter "page:*/blog/*"

# Group by page instead of query
gsc-cli queries --dimension page

# Export to CSV
gsc-cli queries --csv output.csv

# JSON output
gsc-cli queries --json

Compare Date Ranges

# This week vs last week
gsc-cli compare --period week

# This month vs last month
gsc-cli compare --period month

# Custom date ranges
gsc-cli compare --from-start 2025-01-01 --from-end 2025-01-15 \
            --to-start 2024-12-15 --to-end 2024-12-31

# Sort by impressions
gsc-cli compare --sort impressions

# Export comparison
gsc-cli compare --csv comparison.csv

Detect Ranking Drops

# Find queries that dropped >5 positions
gsc-cli drops

# Lower threshold (>3 positions)
gsc-cli drops --threshold 3

# Only queries with significant traffic
gsc-cli drops --min-clicks 10

# Compare 14-day periods
gsc-cli drops --days 14

# Export drops
gsc-cli drops --csv drops.csv

List Sites

# Show all sites you have access to
gsc-cli sites

This displays the exact site URL format to use.

Configuration

# Set default site
gsc-cli config set-site sc-domain:example.com

# Show current config
gsc-cli config show

Authentication

# Check auth status
gsc-cli auth status

# Log out (removes stored token)
gsc-cli auth logout

Global Flags

Flag	Description
-s, --site	Override default site URL
--json	Output as JSON
--no-color	Disable colored output

Shell Completion

# Bash
source <(gsc-cli completion bash)

# Zsh
source <(gsc-cli completion zsh)

# Fish
gsc-cli completion fish | source

Site URL Formats

Google Search Console uses two property types:

• Domain property: sc-domain:example.com
• URL prefix: https://example.com/

Use the exact format shown in your Search Console dashboard.

Security

• OAuth tokens are stored in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service)
• The client_secret.json path is stored in ~/.config/gsc-cli/config.yaml
• No credentials are stored in plaintext files

License

MIT