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 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

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

Both SearchDock and setup skills are published on ClawHub. Its skill copies use MIT-0, as required by that registry; this repository and its packages remain MIT licensed.

The local MCPB bundle is published on Smithery. It requires Node.js 22+ and a locally authenticated Google profile; it includes no credentials. python scripts/build_mcpb.py packages a built dist/cli.cjs. Release and discovery automation.

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.