searchdock-cli 0.1.1__py3-none-any.whl

searchdock_cli/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

searchdock_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: searchdock-cli
+Version: 0.1.1
+Summary: Google Search Console CLI with agent skills and MCP support. Requires Node.js 22+.
+Author-email: Xplormity Collective <xplormityai@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xplormityai/searchdock-cli
+Project-URL: Documentation, https://github.com/xplormityai/searchdock-cli#readme
+Project-URL: Issues, https://github.com/xplormityai/searchdock-cli/issues
+Project-URL: Source, https://github.com/xplormityai/searchdock-cli
+Keywords: google-search-console,seo,cli,mcp,search-analytics
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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.**
+
+## Install
+
+Node.js **22 or later** is required for every distribution.
+
+Packages: [npm](https://www.npmjs.com/package/searchdock-cli) · [PyPI](https://pypi.org/project/searchdock-cli/).
+
+```sh
+# npm
+npm install --global searchdock-cli
+searchdock --help
+
+# No global installation
+npx --yes searchdock-cli@0.1.1 --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.
+
+To run from source:
+
+```sh
+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](https://github.com/xplormityai/searchdock-cli/blob/main/docs/google-setup.md) for the steps and testing-mode limits. No shared developer credentials are included.
+
+```sh
+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](https://github.com/xplormityai/searchdock-cli/blob/main/docs/privacy.md).
+
+## Commands
+
+```sh
+# 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:
+
+```json
+{
+  "mcpServers": {
+    "searchdock": {
+      "command": "npx",
+      "args": ["--yes", "searchdock-cli@0.1.1", "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.1", "mcp"]`. Use your client's Windows configuration guidance.
+
+Plugins use the same pinned npm version:
+
+```sh
+# Codex CLI
+codex plugin marketplace add xplormityai/searchdock-cli
+codex plugin add searchdock@searchdock
+```
+
+In Claude Code:
+
+```text
+/plugin marketplace add xplormityai/searchdock-cli
+/plugin install searchdock@searchdock
+```
+
+For a standalone skill, copy [`skills/searchdock`](https://github.com/xplormityai/searchdock-cli/blob/main/skills/searchdock) into your agent's skills directory. Codex uses `~/.agents/skills/`; Claude Code uses `~/.claude/skills/`. Install the CLI separately. The setup skill is 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](https://github.com/vercel-labs/skills):
+
+```sh
+npx skills add xplormityai/searchdock-cli --skill searchdock
+```
+
+[`server.json`](https://github.com/xplormityai/searchdock-cli/blob/main/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
+
+| Available | Requires Search Console UI or an export |
+| --- | --- |
+| Clicks, impressions, CTR, average position | Request indexing |
+| Top queries/pages and date/device/country breakdowns | Test a live URL |
+| Exact brand-query performance | Full Page indexing exclusions table |
+| Sitemap processing status | Manual actions and security issues |
+| Google's indexed version of specific URLs | Guaranteed current ranking or indexing |
+
+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
+
+```js
+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](https://github.com/xplormityai/searchdock-cli/blob/main/docs/architecture.md).
+
+## Develop and release
+
+```sh
+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.1-py3-none-any.whl dist/releases/searchdock_cli-0.1.1.tar.gz
+```
+
+[Release instructions](https://github.com/xplormityai/searchdock-cli/blob/main/docs/releasing.md) 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](https://github.com/xplormityai/searchdock-cli/blob/main/LICENSE).

searchdock_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+searchdock_cli/__init__.py,sha256=h86OIT3tLUqS-dCVwhgPn4kOUL0RbVfrpeeKKm2CU7U,1112
+searchdock_cli/__main__.py,sha256=BHLi_-4Bx1gsZn-z6x7wECPn1YTxdc74y0deRea9FzY,45
+searchdock_cli/_version.py,sha256=rnObPjuBcEStqSO0S6gsdS_ot8ITOQjVj_-P1LUUYpg,22
+searchdock_cli/_core/THIRD_PARTY_NOTICES.md,sha256=qTN_1AgIbaIu3r-Anmo490He6LCyiNdupLZ5VamF0HM,9385
+searchdock_cli/_core/cli.cjs,sha256=YiJjxSAoytE6Y1cEG-WzFkLGAYrFzmEXK_6GwcR7IwE,373958
+searchdock_cli-0.1.1.dist-info/licenses/LICENSE,sha256=cyErkIQjY70rH_U2x97HnRMJbq5GPRFe5I23B2PROPY,1077
+searchdock_cli-0.1.1.dist-info/METADATA,sha256=dIQu_oot3u91aUzmyjvzRQnIeq83LCMpiGMAbdzO040,8606
+searchdock_cli-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+searchdock_cli-0.1.1.dist-info/entry_points.txt,sha256=iUGO9GmzGgfxsAk96yPbbYCZEbprbhS-mKqnK_YjOG8,51
+searchdock_cli-0.1.1.dist-info/top_level.txt,sha256=lZ3GQgXeM_oE3OzgvU_aiTNwC65wfLedrMh5G9IBo5I,15
+searchdock_cli-0.1.1.dist-info/RECORD,,

searchdock_cli-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

searchdock_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+searchdock = searchdock_cli:main

searchdock_cli-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xplormity Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

searchdock_cli-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+searchdock_cli