GSC CLI

Install the command

GSC CLI needs Node.js 22 or later on macOS or Linux. It uses your own Google Cloud project and Google account with access to Search Console.

After purchasing, connect your GitHub account in Polar and accept the invitation. Download the ZIP and checksum file from the private GSC releases. Verify the download with shasum -a 256 -c SHA256SUMS on macOS, or sha256sum -c SHA256SUMS on Linux. Unzip it, open Terminal in that folder, and run:

./install.sh

The installer copies the runtime to ~/.local/share/gsc/releases/ and links ~/.local/bin/gsc. Make sure ~/.local/bin is on your PATH. If the command is missing, add this line to your shell configuration and reopen Terminal:

export PATH="$HOME/.local/bin:$PATH"

Check with gsc --version. You can delete the downloaded folder after installation.

Connect Google

In your Google Cloud project, enable the Search Console API, configure OAuth consent, and create an OAuth client with type Desktop app. Download its client JSON. If your consent app is in Testing, add your Google account as a test user.

Use the same account that can access your Search Console properties. Start login with your downloaded file:

gsc login --client ~/Downloads/google-desktop-client.json

Finish the browser consent on the same computer. The CLI requests read-only access and saves its own connection. It does not borrow credentials from another app. Run gsc guide for the full setup instructions, or consult Google’s Desktop OAuth guide if console labels change.

Check the connection and list properties:

gsc auth status --check
gsc sites

Copy the exact siteUrl into later commands. Domain properties use sc-domain:your-domain; URL-prefix properties include the protocol and trailing slash. The following examples use https://flaviocopes.com/; replace that with a property your account owns.

Find the pages bringing search traffic

This query groups results by page for an explicit period:

gsc query --site https://flaviocopes.com/ \
  --start 2026-10-01 --end 2026-10-25 \
  --dimensions page --all

Data commands return JSON. Each row contains its dimension keys, clicks, impressions, CTR and average position. CTR is a fraction: 0.05 means 5%. Dates are inclusive and follow Google’s Pacific reporting calendar.

Use --dimensions query,page to see search terms alongside their pages. To inspect one section of a site, add a filter:

gsc query --site https://flaviocopes.com/ \
  --start 2026-10-01 --end 2026-10-25 \
  --dimensions query,page \
  --filter '{"dimension":"page","operator":"contains","expression":"/javascript"}' \
  --all

Omit dimensions for property totals. Query rows can omit anonymized searches, so adding them up does not produce reliable property totals.

Check sitemaps and indexed pages

List submitted sitemaps:

gsc sitemaps --site https://flaviocopes.com/

Read the children of a sitemap index with --index URL, or details of one submitted sitemap with --sitemap URL.

Inspect Google’s saved index information for a page:

gsc inspect --site https://flaviocopes.com/ --url https://flaviocopes.com/javascript/

Inspection reports Google’s indexed copy, including available crawl and canonical information. It does not perform a live crawl or request indexing. The CLI has no write commands for sitemap submission or property changes.

Read complete results carefully

Without --all, a query returns up to 1,000 rows. With it, GSC fetches successive pages up to its collection budget, 100,000 rows by default. Check pagination.rowLimitReached and nextStartRow before treating a response as complete. Use --max-rows to change the budget or --start-row to resume.

Google still omits anonymized queries and limits which rows it exposes. Pagination cannot recover missing API data. Fresh data can change, and quotas apply. The links report, Core Web Vitals and full page-indexing dashboard are outside this CLI’s API coverage.

Use it with an agent

Install the bundled skill for your agent:

gsc skill install --target codex

Use claude or cursor for the other supported targets, then reload the agent. Ask it to compare equal periods, identify pages that lost clicks, and inspect the terms associated with those pages. gsc capabilities --json describes available commands.

Troubleshooting and updates

A permission error usually means the Google account lacks property access or the Search Console API is disabled. Reconnect with gsc login if consent expires or is revoked. gsc logout removes the local refresh token; revoking the grant in Google is separate.

Credentials live in ~/.config/gsc/credentials.json. Keep this folder out of Git and shared screenshots. Download a newer release and rerun its installer to update. Your connection remains separate from the installed code.