SearchDock CLI — Google Search Console CLI

Read Google Search Console analytics, inspect indexed URLs, and monitor sitemaps from your terminal or AI agent.

SearchDock is open source, runs locally, and requests read-only Google access. Use the same core through npm, Python, MCP, a Codex or Claude Code plugin, or a standalone agent skill. Bing Webmaster Tools support is planned.

Set up with your agent

Copy this prompt into your coding agent:

Set up SearchDock CLI for this project using
https://github.com/xplormityai/searchdock-cli. Read its README and
skills/searchdock-setup/SKILL.md. Check Node.js 22+, reuse an existing
installation, or install the CLI from npm. Install searchdock-setup and
searchdock skills for the agent I am using, scoped to this project, and
connect the stdio MCP server if this agent supports it. Keep existing
agent configuration. For Google access, ask only for the local path to
my Desktop OAuth client JSON and guide me through read-only browser
consent. Never print credentials or tokens. Let me choose the Search
Console property, then verify the connection with a metrics request.
Tell me exactly which steps succeeded and what still needs my input.

Installation commands

Node.js 22 or later is required for every distribution.

Packages: npm · PyPI.

# npm
npm install --global searchdock-cli
searchdock --help

# No global installation
npx --yes searchdock-cli@0.1.3 --help

# Python; Node.js is still required
pipx install searchdock-cli
# Alternatively: python -m pip install searchdock-cli

The Python package is a launcher containing the exact same JavaScript runtime. It has no separate Google implementation. If you install both packages, use python -m searchdock_cli to select the Python launcher explicitly.

Install both skills for Codex in the current project:

npx --yes skills add xplormityai/searchdock-cli --skill searchdock-setup searchdock --agent codex --copy --yes

Replace codex with claude-code, cursor, opencode, or your supported agent. Add --global only for installation across projects. Skills do not install the CLI or authorize Google access. Plugin, MCP and manual setup.

To run from source:

git clone https://github.com/xplormityai/searchdock-cli.git
cd searchdock-cli
npm ci
npm run build
node dist/cli.cjs --help

Connect Google Search Console

Create a Google OAuth Desktop app client in your own Google Cloud project, enable the Search Console API, and download the client JSON. See Google setup for the steps and testing-mode limits. No shared developer credentials are included.

searchdock auth login --client-file /path/to/desktop-client.json
searchdock sites list
searchdock sites use sc-domain:example.com
searchdock auth status

Google opens a local browser consent flow. SearchDock uses PKCE, validates the callback state, and listens only on 127.0.0.1. It requests webmasters.readonly and keeps the refresh token in your operating system's per-user configuration directory, outside this repository. Credentials are stored as permission-protected local JSON, not encrypted by SearchDock. See privacy.

Commands

# Search performance and top queries
searchdock analytics --days 28
searchdock analytics --dimensions page --days 28 --json
searchdock analytics --dimensions date --start 2026-09-01 --end 2026-09-30

# Exact, case-insensitive brand queries
searchdock analytics --brand "Your Brand" --json

# Sitemaps and Google's indexed URL status
searchdock sitemaps
searchdock inspect https://example.com/

# Combined report, including only the URLs you specify
searchdock report --urls https://example.com/,https://example.com/about --json
searchdock report --output ./private-report.json

# Multiple accounts/sites
searchdock auth login --client-file /path/to/client.json --profile work
searchdock sites use https://example.com/ --profile work
searchdock analytics --profile work --site https://example.com/ --json

# Diagnostics and local credential removal
searchdock doctor
searchdock auth logout

--json writes machine-readable results to stdout and errors to stderr with a nonzero exit status. --output saves JSON to a new file and refuses to overwrite an existing one. Keep private reports out of Git yourself. CSV is not yet supported. For URLs containing commas, use the MCP urls array or the JavaScript API for batch inspection.

Report windows default to 28 days ending three days before today in Pacific Time, to allow for Search Console processing. You can specify exact dates. Finalized data may still lag. Pagination supports up to 100,000 requested rows, but Google's API returns top rows and omits some anonymized query data. Missing rows do not prove zero demand; zero impressions make average position meaningless.

AI agents and MCP

SearchDock provides five read-only MCP tools: searchdock_sites, searchdock_analytics, searchdock_sitemaps, searchdock_inspect, and searchdock_report. Authenticate locally first; MCP tools do not start consent or change account settings.

Add this stdio server to any compatible MCP client:

{
  "mcpServers": {
    "searchdock": {
      "command": "npx",
      "args": ["--yes", "searchdock-cli@0.1.3", "mcp"]
    }
  }
}

For a source checkout, set command to node and args to ["/absolute/path/searchdock-cli/dist/cli.cjs", "mcp"]. Windows clients that launch npx.cmd through a shell may need command: "cmd" and args: ["/c", "npx", "--yes", "searchdock-cli@0.1.3", "mcp"]. Use your client's Windows configuration guidance.

Plugins use the same pinned npm version:

# Codex CLI
codex plugin marketplace add xplormityai/searchdock-cli
codex plugin add searchdock@searchdock

In Claude Code:

/plugin install searchdock --marketplace xplormityai/searchdock-cli --scope project

This one-step command requires Claude Code 2.1.275+. Earlier versions can use /plugin marketplace add xplormityai/searchdock-cli, then /plugin install searchdock@searchdock --scope project.

For standalone skills, copy both skills/searchdock and skills/searchdock-setup into your agent's skills directory. Codex uses ~/.agents/skills/; Claude Code uses ~/.claude/skills/. Install the CLI separately. Both skills are included in the plugin. The repository includes portable Agent Plugins, Codex and Claude manifests; local stdio plugins are not automatically listed in hosted plugin directories.

You can also install the skill with the open skills installer:

npx --yes skills add xplormityai/searchdock-cli --skill searchdock-setup searchdock --agent codex --copy --yes

server.json prepares a listing in the MCP Registry under io.github.xplormityai/searchdock-cli. Registry publication requires the npm package to be live and namespace authentication; the metadata file alone does not create a listing.

What the Google API can and cannot tell you

SearchDock's report flags returned sitemap errors/warnings, pending processing and non-PASS verdicts for the URLs you inspect. It is not a complete technical SEO audit, and it does not provide invented SEO/AEO/GEO scores.

JavaScript API

import { selectedContext } from 'searchdock-cli';

const { adapter, site } = await selectedContext({ profile: 'default' });
const result = await adapter.analytics(site, { days: 28, dimensions: ['page'] });
console.log(result.rows);

The provider registry declares capabilities separately. Bing can be added as an adapter without changing the CLI, MCP or Python distribution model. Provider-specific differences must remain explicit. See architecture.

Develop and release

npm ci
npm run build
npm test
npm run check
python -m pip install build twine
npm run release:artifacts
python -m twine check dist/releases/searchdock_cli-0.1.3-py3-none-any.whl dist/releases/searchdock_cli-0.1.3.tar.gz

Release instructions cover npm/PyPI accounts, OIDC trusted publishing, versioning and GitHub release artifacts. Package creation alone does not publish anything.

Built by Xplormity Collective. MIT license.