Docs | SearchProbe

Install the current beta

SearchProbe is a native binary named gsc. The pinned GitHub Release installer supports macOS and Linux on arm64 and amd64, verifies SHA256, and installs in a user-owned directory without sudo or shell-profile edits. Windows is not currently supported, and release binaries are unsigned.

curl --proto '=https' --proto-redir '=https' --tlsv1.2 --fail --location \
  https://github.com/morgancrozier/searchprobe/releases/download/v0.1.0-beta.4/install.sh \
  -o install-searchprobe.sh
sh ./install-searchprobe.sh --version v0.1.0-beta.4

Package installation installs only the binary. Google access and agent skills are configured explicitly afterward. Ghostscript also provides a gsc executable; the installer does not overwrite or delete it. See the installation guide for PATH setup, updates, credential-preserving removal, and platform details.

Set up Google access

Create or select a project in the Google Cloud Console, enable the Google Search Console API, configure Google Auth Platform, and create a Desktop app OAuth client. Request only https://www.googleapis.com/auth/webmasters.readonly, then download the client JSON and run:

"$HOME/.local/share/searchprobe/bin/gsc" setup --client-file "$HOME/Downloads/client.json"

Sign in with a Google account that already has access to the Search Console property. SearchProbe imports your client and stores credentials locally, preferring macOS Keychain or Linux Secret Service. Protected plaintext file storage is used only after explicit selection. After SearchProbe confirms persistence, you may delete the downloaded JSON. Never commit it or paste its contents into a chat.

Follow the canonical Google OAuth setup guide for audience settings, credential storage, token lifetime, and headless Linux guidance.

Verify access and run a query

export PATH="$HOME/.local/share/searchprobe/bin:$PATH"
hash -r
gsc --version
gsc sites --json

Confirm that gsc --version identifies SearchProbe. Copy an exact property identifier from gsc sites, including the sc-domain: prefix or URL-prefix trailing slash, and use it in your first query:

gsc performance \
  --site sc-domain:example.com \
  --days 28 \
  --dimensions page \
  --json

JSON responses include typed data, metadata, and warnings. Search Analytics exposes top rows and may be incomplete, dates use Pacific Time, and finalized data can lag. Use gsc <command> --help and the canonical references below instead of guessing flags or interpreting missing rows as zero activity.

Use SearchProbe with coding agents

Interactive gsc setup detects Claude Code and Codex, verifies Google access, and can install the bundled SearchProbe skill. You can also manage skills independently:

gsc agent install --agent claude
gsc agent install --agent codex
gsc agent status --json

Start a fresh agent session after installation or PATH changes. Skill status proves the managed files match the installed binary, not that an agent has loaded them. Then ask a natural question such as:

Which pages lost the most Google visibility in the last 28 days, and are there code changes in this repository that might explain it?

The skill guides the agent to use deterministic CLI evidence, inspect relevant repository history, and separate Search Console observations from causal hypotheses. Read the agent integration guide for setup choices, discovery checks, sandbox requirements, and troubleshooting.

Use the local MCP server

MCP-capable clients can launch SearchProbe after gsc setup has stored working credentials:

gsc mcp

The session exposes sites, performance, compare, inspect, sitemaps, and sitemap as structured, read-only tools over stdio. The local process uses the same credentials and talks directly to Google. It opens no port, starts no browser login, and runs only for the client session. Configure the MCP client separately; SearchProbe does not change Claude Code or Codex MCP settings.

Command summary

Search Console operations are read-only. Add --json for structured output where supported, and use gsc <command> --help for flags and examples.

Command	What it does
`gsc setup`	Connect Google, verify access, and prepare selected agent skills
`gsc auth login`	Sign in with the saved Google Cloud Desktop OAuth client
`gsc auth status`	Inspect local authentication state without a network call
`gsc auth logout`	Attempt revocation and remove the saved client and tokens
`gsc agent install`	Install or update the bundled Claude Code or Codex skill
`gsc agent status`	Inspect managed skill status for both supported agents
`gsc agent uninstall`	Remove verified managed skill copies
`gsc sites`	List accessible Search Console properties
`gsc performance`	Query clicks, impressions, CTR, and average position
`gsc compare`	Compare two Search Analytics date windows
`gsc inspect`	Inspect Google's indexed version of one or more URLs
`gsc sitemaps`	List submitted sitemaps for a property
`gsc sitemap`	Show details for one submitted sitemap
`gsc mcp`	Run the six read-only Search Console tools as a local stdio MCP server

Canonical technical reference

The website is an onboarding summary. The public GitHub repository owns release status, exact syntax, API semantics, architecture, error behavior, and roadmap details.