Searchdock Cli

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 usinghttps://github.com/xplormityai/searchdock-cli. Read its README andskills/searchdock-setup/SKILL.md. Check Node.js 22+, reuse an existinginstallation, or install the CLI from npm. Install searchdock-setup andsearchdock skills for the agent I am using, scoped to this project, andconnect the stdio MCP server if this agent supports it. Keep existingagent configuration. For Google access, ask only for the local path tomy Desktop OAuth client JSON and guide me through read-only browserconsent. Never print credentials or tokens. Let me choose the SearchConsole 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.

# npmnpm install --global searchdock-clisearchdock --help
# No global installationnpx --yes [email protected] --help
# Python; Node.js is still requiredpipx 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.gitcd searchdock-clinpm cinpm run buildnode 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.jsonsearchdock sites listsearchdock sites use sc-domain:example.comsearchdock 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 queriessearchdock analytics --days 28searchdock analytics --dimensions page --days 28 --jsonsearchdock analytics --dimensions date --start 2026-09-01 --end 2026-09-30
# Exact, case-insensitive brand queriessearchdock analytics --brand "Your Brand" --json
# Sitemaps and Google's indexed URL statussearchdock sitemapssearchdock inspect https://example.com/
# Combined report, including only the URLs you specifysearchdock report --urls https://example.com/,https://example.com/about --jsonsearchdock report --output ./private-report.json
# Multiple accounts/sitessearchdock auth login --client-file /path/to/client.json --profile worksearchdock sites use https://example.com/ --profile worksearchdock analytics --profile work --site https://example.com/ --json
# Diagnostics and local credential removalsearchdock doctorsearchdock 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", "[email protected]", "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", "[email protected]", "mcp"]. Use your client's Windows configuration guidance.

Plugins use the same pinned npm version:

# Codex CLIcodex plugin marketplace add xplormityai/searchdock-clicodex 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

SearchDock is published in the official MCP Registry under io.github.xplormityai/searchdock-cli. Release workflows update its metadata using GitHub OIDC.

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 cinpm run buildnpm testnpm run checkpython -m pip install build twinenpm run release:artifactspython -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.