rankrush-cli 0.1.37__tar.gz

rankrush_cli-0.1.37/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Gircenko
+
+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.

rankrush_cli-0.1.37/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: rankrush-cli
+Version: 0.1.37
+Summary: Agent-native CLI wrapper for the RankRush platform — wraps Supabase Edge Functions and REST API into structured, scriptable commands with --json output.
+Author-email: Gabriel Gircenko <gabriel.gircenko@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://rankrush.ai
+Project-URL: Repository, https://github.com/nikolapevic/rankrush
+Keywords: rankrush,seo,aeo,ai-visibility,cli,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: urllib3<3,>=2.1
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: pydantic>=2.11
+Requires-Dist: typing-extensions>=4.7.1
+Requires-Dist: certifi>=2024.2.2
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: coverage>=7.4; extra == "dev"
+Requires-Dist: mcp>=1.2; extra == "dev"
+Dynamic: license-file
+
+# rankrush-cli
+
+[![CLI Test Matrix](https://github.com/nikolapevic/rankrush/actions/workflows/cli-test-matrix.yml/badge.svg?branch=main)](https://github.com/nikolapevic/rankrush/actions/workflows/cli-test-matrix.yml)
+![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Agent-native command-line interface for [RankRush](https://rankrush.ai) — the AI visibility and on-site SEO platform. The CLI wraps RankRush's edge functions and REST API into structured, scriptable commands with `--json` output, so humans on a terminal and agents like Claude Code can interact with the platform without a browser.
+
+Inspired by [CLI-Anything](https://github.com/HKUDS/CLI-Anything): *"Today's Software Serves Humans. Tomorrow's Users will be Agents."*
+
+- **Homepage:** <https://rankrush.ai>
+- **Source:** <https://github.com/nikolapevic/rankrush>
+- **Issues:** <https://github.com/nikolapevic/rankrush/issues>
+- **License:** MIT (see [LICENSE](LICENSE))
+
+---
+
+## Install
+
+```bash
+pip install rankrush-cli
+```
+
+Requires Python 3.10, 3.11, or 3.12.
+
+**Developing locally** (clone the repo first):
+
+```bash
+git clone https://github.com/nikolapevic/rankrush.git
+cd rankrush/cli
+python3 -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+Verify the install:
+
+```bash
+rankrush --version
+rankrush --help
+```
+
+`rankrush init` writes `~/.config/rankrush/.env` (or `./.env` with
+`--target cwd`) with `0600` permissions. Re-run any time to update the key.
+
+> **Working in the repo?** Developers can also place values in
+> `cli/.env` for repo-local overrides. Shell exports → `cli/.env` →
+> `~/.config/rankrush/.env` is the resolution order, first wins.
+
+---
+
+## Authenticate
+
+1. Sign in at <https://rankrush.ai> and open **Settings → API Keys**.
+2. Click **Generate key**. Your key looks like `rr_live_<random>`. Copy it.
+3. Run the setup wizard:
+
+```bash
+rankrush init
+```
+
+The wizard prompts for `RANKRUSH_API_KEY`, writes it to `~/.config/rankrush/.env` (mode `0600`), and validates the key against the live backend. Re-run any time to update the key.
+
+Resolution order for the API key (first match wins):
+
+1. Shell environment (`export RANKRUSH_API_KEY=...`).
+2. `./.env` in the current working directory (use `rankrush init --target cwd` to scaffold it).
+3. `~/.config/rankrush/.env` (default `rankrush init` target).
+
+To override without an interactive prompt:
+
+```bash
+rankrush init --api-key rr_live_xxx --skip-validate    # offline machines
+rankrush init --force                                  # overwrite without confirmation
+```
+
+### Testing against stage
+
+`--stage` points any command at the stage environment (`app.stage.rankrush.ai`)
+instead of production — the stage URL and publishable key are bundled, so you
+only need a stage API key. Configure it once, then prefix commands with
+`--stage`:
+
+```bash
+rankrush init --stage          # paste a stage key (from app.stage.rankrush.ai → Settings → API Keys)
+rankrush --stage smoke
+rankrush --stage audit run --profile-id <stage-profile-id>
+```
+
+The stage key is stored as `RANKRUSH_STAGE_API_KEY` (separate from your prod
+`RANKRUSH_API_KEY`, same env file), so prod and stage never collide. Power users
+can also point at any backend with `RANKRUSH_SUPABASE_URL` +
+`SUPABASE_PUBLISHABLE_KEY`.
+
+---
+
+## Your first 5 minutes
+
+After `rankrush init` succeeds, run these three commands in order:
+
+```bash
+# 1. Confirm the live backend accepts your key and the four edge functions are healthy.
+rankrush smoke
+
+# 2. List the business profiles in your account. Copy a profile UUID for the next step.
+rankrush profiles list
+
+# 3. Run a full AI visibility check — keywords, ChatGPT/Claude/Perplexity/Gemini scores, citations.
+rankrush visibility check --profile-id <profile-id>
+```
+
+If `rankrush smoke` reports a 401, your key is wrong or missing — re-run `rankrush init`. If it reports a network error, you're offline or behind a proxy.
+
+Every command supports `--json` for machine-readable output.
+
+---
+
+## Command reference
+
+| Command | Description |
+|---|---|
+| `rankrush init` | Interactive setup wizard. Writes API key to `~/.config/rankrush/.env`, validates against the backend. Flags: `--target user\|cwd`, `--api-key`, `--publishable-key`, `--skip-validate`, `--force`, `--stage` (configure the stage key). |
+| _global_ `--stage` | Prefix any command to target stage (`app.stage.rankrush.ai`): `rankrush --stage smoke`. Uses `RANKRUSH_STAGE_API_KEY`. |
+| `rankrush smoke` | Health-check the critical edge functions. Exits 0 if all pass, 1 otherwise. |
+| `rankrush profiles list` | List all business profiles belonging to your API key. |
+| `rankrush keywords generate` | Generate AEO keywords via the LLM and replace the profile's tracked set in `aeo_keywords`. Flags: `--profile-id`, `--json`. |
+| `rankrush keywords list` | Show the currently tracked AEO keywords for a profile. Flags: `--profile-id`, `--json`. |
+| `rankrush visibility check` | Run a full AI visibility analysis for a profile (ChatGPT, Claude, Perplexity, Gemini). |
+| `rankrush visibility delta` | Compare the two most recent cached visibility snapshots for a profile. |
+| `rankrush audit run` | Trigger a full bulk on-site website audit (legacy v1, synchronous). Flags: `--url` (required), `--profile-id`, `--industry b2b_saas\|local_service\|ecommerce`, `--language`, `--force-refresh`, `--json`. |
+| `rankrush audit start` | Enqueue a v2 audit (writes to `audit_runs`/`node_progress`, visible in the web app). Flags: `--profile-id`, `--node-id` (single-node mode), `--wait`, `--poll-interval`, `--timeout`, `--json`. |
+| `rankrush audit status` | Show the current status of a v2 audit run. Arg: `<run-id>`. Flags: `--json`. |
+| `rankrush audit get` | Fetch the full `audit_runs` row plus an aggregated per-node summary. Arg: `<run-id>`. Flags: `--json`. |
+| `rankrush audit delete` | Permanently delete an audit run and its node rows (admin-only). Arg: `<run-id>`. Flags: `--json`. |
+| `rankrush nodes list` | List `node_progress` rows for a profile. Flags: `--profile-id`, `--status`, `--json`. |
+| `rankrush nodes suggestions` | Surface `recommended_fixes` for nodes that still need work, each stamped with a stable `suggestion_id`. Flags: `--profile-id`, `--include-resolved`, `--json`. |
+| `rankrush nodes complete` | Mark a node `status='complete'` (notify back from the vault). Arg: `<node-id>`. Flags: `--profile-id`, `--json`. |
+| `rankrush leadgen harvest` | Mine Common Crawl WAT shards into the `cc_citation_leads` lead store. Flags: `--crawl`, `--shards`, `--seed`, `--workers`, `--dry-run`, `--out`, `--json`. |
+| `rankrush buzz research refresh` | Pull new Reddit/Quora mentions for a profile. |
+| `rankrush buzz research highlights` | List high-relevance unseen research mentions, best-first. |
+| `rankrush buzz strategy suggest` | Generate a Reddit posting strategy from the profile's research. |
+| `rankrush buzz drafts list` | List Buzz posts filtered by status (`draft`/`approved`/`scheduled`/`posted`/`failed`). |
+| `rankrush buzz drafts approve` | Approve a draft post, optionally scheduling it. |
+| `rankrush buzz posts performance` | Show published posts within a time window. |
+| `rankrush report daily` | Composite daily digest: visibility delta + research highlights + draft count. |
+| `rankrush report weekly` | 7-day visibility trend + post performance + AEO gap analysis. |
+| `rankrush report aeo-gaps` | List AI platforms where visibility score is below a threshold. |
+| `rankrush blog topics generate` | Generate blog topics for a profile over an N-day window (`--days`, default 30, clamped 1–180). |
+| `rankrush blog topics list` | List tracked blog topics (title / generation stage / scheduled-for) for a profile. |
+| `rankrush blog post generate` | Draft a full blog post from a topic (`--topic-id`). Requires a CMS connection; subject to a tier daily cap. |
+| `rankrush blog strategy` | Generate an overall content strategy for a profile. |
+| `rankrush cms connect` | Verify and store CMS (WordPress app-password) credentials for a profile. Username + app password are collected via **hidden prompts**, never flags. |
+| `rankrush scans enqueue` | Enqueue a background scan (`ai_visibility`/`web_audit`/`node_check`) for a profile. Optional `--url` override and `--priority`. |
+| `rankrush leads create` | **Admin-only.** Create a RankRush account for a sales lead, run a first-impression scan, and return a set-password invite link. |
+| `rankrush repl` | Start an interactive REPL — run commands without the `rankrush` prefix. |
+
+Every command accepts `--help` and (where applicable) `--json`. The top-level `--debug` flag re-raises the underlying exception with a full traceback instead of the friendly one-line message.
+
+---
+
+## Common workflows
+
+### Daily check
+
+```bash
+rankrush visibility check --profile-id <id>      # caches snapshot in ~/.rankrush/cache/
+rankrush buzz research refresh --profile-id <id>
+rankrush report daily --profile-id <id> --json
+```
+
+`report daily` reads from the local cache; run `visibility check` and `research refresh` first.
+
+### Compare two visibility snapshots
+
+```bash
+# Day 1
+rankrush visibility check --profile-id <id>
+
+# Day 2
+rankrush visibility check --profile-id <id>
+rankrush visibility delta --profile-id <id> --threshold 5
+```
+
+`delta` flags drops greater than the threshold (default 5 points).
+
+### Approve a Buzz draft and schedule it
+
+```bash
+rankrush buzz drafts list --profile-id <id>
+rankrush buzz drafts approve --id <draft-uuid> --schedule-at 2026-05-15T09:00:00Z
+```
+
+### Create a lead account (admin)
+
+```bash
+rankrush leads create \
+  --business-name "Acme Co" \
+  --website-url https://acme.example \
+  --industry b2b_saas \
+  --location Berlin            # optional; used for local_service relevance
+# (you are prompted for the lead's email so it never lands in shell history)
+```
+
+Requires an **admin** `rr_live_*` api key — the backend verifies the caller's
+role. The command returns an invite (set-password) link to share with the lead
+plus a summary of the first-impression ChatGPT visibility scan. A 401/403
+means the key is not an admin key.
+
+---
+
+## Troubleshooting
+
+### `Authentication failed` / HTTP 401
+
+Your `RANKRUSH_API_KEY` is missing or invalid. Re-run:
+
+```bash
+rankrush init
+```
+
+The wizard validates the key against the backend before saving.
+
+### Network errors / timeouts
+
+Check your internet connection. The CLI talks to RankRush's Supabase backend over HTTPS — corporate proxies, VPNs with HTTPS inspection, and offline machines will all break it.
+
+### `Command failed with cryptic error`
+
+Add `--debug` before the command to see the full traceback:
+
+```bash
+rankrush --debug visibility check --profile-id <id>
+```
+
+Open an issue with that output at <https://github.com/nikolapevic/rankrush/issues>.
+
+### Want to verify your install end-to-end
+
+```bash
+rankrush --version           # → rankrush, version 0.1.15
+rankrush smoke               # → all edge functions green
+rankrush profiles list       # → at least one profile
+```
+
+If all three pass, you're set up correctly.
+
+---
+
+## Use it from an AI client (MCP)
+
+`pip install "rankrush-cli[mcp]"` also installs **`rankrush-mcp`**, a Model Context Protocol server that exposes these commands as tools so Claude Desktop / Claude Code / Cursor can drive RankRush directly. Setup + tool list: [docs/mcp.md](docs/mcp.md).
+
+## Versioning & changelog
+
+`rankrush-cli` follows [Semantic Versioning](https://semver.org/). Every release is recorded in [CHANGELOG.md](CHANGELOG.md); the versioning policy and release-cut checklist live in [docs/versioning.md](docs/versioning.md).
+
+## Contributing
+
+PRs and issues welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, test commands, and the PR checklist.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

rankrush_cli-0.1.37/README.md

@@ -0,0 +1,263 @@
+# rankrush-cli
+
+[![CLI Test Matrix](https://github.com/nikolapevic/rankrush/actions/workflows/cli-test-matrix.yml/badge.svg?branch=main)](https://github.com/nikolapevic/rankrush/actions/workflows/cli-test-matrix.yml)
+![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Agent-native command-line interface for [RankRush](https://rankrush.ai) — the AI visibility and on-site SEO platform. The CLI wraps RankRush's edge functions and REST API into structured, scriptable commands with `--json` output, so humans on a terminal and agents like Claude Code can interact with the platform without a browser.
+
+Inspired by [CLI-Anything](https://github.com/HKUDS/CLI-Anything): *"Today's Software Serves Humans. Tomorrow's Users will be Agents."*
+
+- **Homepage:** <https://rankrush.ai>
+- **Source:** <https://github.com/nikolapevic/rankrush>
+- **Issues:** <https://github.com/nikolapevic/rankrush/issues>
+- **License:** MIT (see [LICENSE](LICENSE))
+
+---
+
+## Install
+
+```bash
+pip install rankrush-cli
+```
+
+Requires Python 3.10, 3.11, or 3.12.
+
+**Developing locally** (clone the repo first):
+
+```bash
+git clone https://github.com/nikolapevic/rankrush.git
+cd rankrush/cli
+python3 -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+Verify the install:
+
+```bash
+rankrush --version
+rankrush --help
+```
+
+`rankrush init` writes `~/.config/rankrush/.env` (or `./.env` with
+`--target cwd`) with `0600` permissions. Re-run any time to update the key.
+
+> **Working in the repo?** Developers can also place values in
+> `cli/.env` for repo-local overrides. Shell exports → `cli/.env` →
+> `~/.config/rankrush/.env` is the resolution order, first wins.
+
+---
+
+## Authenticate
+
+1. Sign in at <https://rankrush.ai> and open **Settings → API Keys**.
+2. Click **Generate key**. Your key looks like `rr_live_<random>`. Copy it.
+3. Run the setup wizard:
+
+```bash
+rankrush init
+```
+
+The wizard prompts for `RANKRUSH_API_KEY`, writes it to `~/.config/rankrush/.env` (mode `0600`), and validates the key against the live backend. Re-run any time to update the key.
+
+Resolution order for the API key (first match wins):
+
+1. Shell environment (`export RANKRUSH_API_KEY=...`).
+2. `./.env` in the current working directory (use `rankrush init --target cwd` to scaffold it).
+3. `~/.config/rankrush/.env` (default `rankrush init` target).
+
+To override without an interactive prompt:
+
+```bash
+rankrush init --api-key rr_live_xxx --skip-validate    # offline machines
+rankrush init --force                                  # overwrite without confirmation
+```
+
+### Testing against stage
+
+`--stage` points any command at the stage environment (`app.stage.rankrush.ai`)
+instead of production — the stage URL and publishable key are bundled, so you
+only need a stage API key. Configure it once, then prefix commands with
+`--stage`:
+
+```bash
+rankrush init --stage          # paste a stage key (from app.stage.rankrush.ai → Settings → API Keys)
+rankrush --stage smoke
+rankrush --stage audit run --profile-id <stage-profile-id>
+```
+
+The stage key is stored as `RANKRUSH_STAGE_API_KEY` (separate from your prod
+`RANKRUSH_API_KEY`, same env file), so prod and stage never collide. Power users
+can also point at any backend with `RANKRUSH_SUPABASE_URL` +
+`SUPABASE_PUBLISHABLE_KEY`.
+
+---
+
+## Your first 5 minutes
+
+After `rankrush init` succeeds, run these three commands in order:
+
+```bash
+# 1. Confirm the live backend accepts your key and the four edge functions are healthy.
+rankrush smoke
+
+# 2. List the business profiles in your account. Copy a profile UUID for the next step.
+rankrush profiles list
+
+# 3. Run a full AI visibility check — keywords, ChatGPT/Claude/Perplexity/Gemini scores, citations.
+rankrush visibility check --profile-id <profile-id>
+```
+
+If `rankrush smoke` reports a 401, your key is wrong or missing — re-run `rankrush init`. If it reports a network error, you're offline or behind a proxy.
+
+Every command supports `--json` for machine-readable output.
+
+---
+
+## Command reference
+
+| Command | Description |
+|---|---|
+| `rankrush init` | Interactive setup wizard. Writes API key to `~/.config/rankrush/.env`, validates against the backend. Flags: `--target user\|cwd`, `--api-key`, `--publishable-key`, `--skip-validate`, `--force`, `--stage` (configure the stage key). |
+| _global_ `--stage` | Prefix any command to target stage (`app.stage.rankrush.ai`): `rankrush --stage smoke`. Uses `RANKRUSH_STAGE_API_KEY`. |
+| `rankrush smoke` | Health-check the critical edge functions. Exits 0 if all pass, 1 otherwise. |
+| `rankrush profiles list` | List all business profiles belonging to your API key. |
+| `rankrush keywords generate` | Generate AEO keywords via the LLM and replace the profile's tracked set in `aeo_keywords`. Flags: `--profile-id`, `--json`. |
+| `rankrush keywords list` | Show the currently tracked AEO keywords for a profile. Flags: `--profile-id`, `--json`. |
+| `rankrush visibility check` | Run a full AI visibility analysis for a profile (ChatGPT, Claude, Perplexity, Gemini). |
+| `rankrush visibility delta` | Compare the two most recent cached visibility snapshots for a profile. |
+| `rankrush audit run` | Trigger a full bulk on-site website audit (legacy v1, synchronous). Flags: `--url` (required), `--profile-id`, `--industry b2b_saas\|local_service\|ecommerce`, `--language`, `--force-refresh`, `--json`. |
+| `rankrush audit start` | Enqueue a v2 audit (writes to `audit_runs`/`node_progress`, visible in the web app). Flags: `--profile-id`, `--node-id` (single-node mode), `--wait`, `--poll-interval`, `--timeout`, `--json`. |
+| `rankrush audit status` | Show the current status of a v2 audit run. Arg: `<run-id>`. Flags: `--json`. |
+| `rankrush audit get` | Fetch the full `audit_runs` row plus an aggregated per-node summary. Arg: `<run-id>`. Flags: `--json`. |
+| `rankrush audit delete` | Permanently delete an audit run and its node rows (admin-only). Arg: `<run-id>`. Flags: `--json`. |
+| `rankrush nodes list` | List `node_progress` rows for a profile. Flags: `--profile-id`, `--status`, `--json`. |
+| `rankrush nodes suggestions` | Surface `recommended_fixes` for nodes that still need work, each stamped with a stable `suggestion_id`. Flags: `--profile-id`, `--include-resolved`, `--json`. |
+| `rankrush nodes complete` | Mark a node `status='complete'` (notify back from the vault). Arg: `<node-id>`. Flags: `--profile-id`, `--json`. |
+| `rankrush leadgen harvest` | Mine Common Crawl WAT shards into the `cc_citation_leads` lead store. Flags: `--crawl`, `--shards`, `--seed`, `--workers`, `--dry-run`, `--out`, `--json`. |
+| `rankrush buzz research refresh` | Pull new Reddit/Quora mentions for a profile. |
+| `rankrush buzz research highlights` | List high-relevance unseen research mentions, best-first. |
+| `rankrush buzz strategy suggest` | Generate a Reddit posting strategy from the profile's research. |
+| `rankrush buzz drafts list` | List Buzz posts filtered by status (`draft`/`approved`/`scheduled`/`posted`/`failed`). |
+| `rankrush buzz drafts approve` | Approve a draft post, optionally scheduling it. |
+| `rankrush buzz posts performance` | Show published posts within a time window. |
+| `rankrush report daily` | Composite daily digest: visibility delta + research highlights + draft count. |
+| `rankrush report weekly` | 7-day visibility trend + post performance + AEO gap analysis. |
+| `rankrush report aeo-gaps` | List AI platforms where visibility score is below a threshold. |
+| `rankrush blog topics generate` | Generate blog topics for a profile over an N-day window (`--days`, default 30, clamped 1–180). |
+| `rankrush blog topics list` | List tracked blog topics (title / generation stage / scheduled-for) for a profile. |
+| `rankrush blog post generate` | Draft a full blog post from a topic (`--topic-id`). Requires a CMS connection; subject to a tier daily cap. |
+| `rankrush blog strategy` | Generate an overall content strategy for a profile. |
+| `rankrush cms connect` | Verify and store CMS (WordPress app-password) credentials for a profile. Username + app password are collected via **hidden prompts**, never flags. |
+| `rankrush scans enqueue` | Enqueue a background scan (`ai_visibility`/`web_audit`/`node_check`) for a profile. Optional `--url` override and `--priority`. |
+| `rankrush leads create` | **Admin-only.** Create a RankRush account for a sales lead, run a first-impression scan, and return a set-password invite link. |
+| `rankrush repl` | Start an interactive REPL — run commands without the `rankrush` prefix. |
+
+Every command accepts `--help` and (where applicable) `--json`. The top-level `--debug` flag re-raises the underlying exception with a full traceback instead of the friendly one-line message.
+
+---
+
+## Common workflows
+
+### Daily check
+
+```bash
+rankrush visibility check --profile-id <id>      # caches snapshot in ~/.rankrush/cache/
+rankrush buzz research refresh --profile-id <id>
+rankrush report daily --profile-id <id> --json
+```
+
+`report daily` reads from the local cache; run `visibility check` and `research refresh` first.
+
+### Compare two visibility snapshots
+
+```bash
+# Day 1
+rankrush visibility check --profile-id <id>
+
+# Day 2
+rankrush visibility check --profile-id <id>
+rankrush visibility delta --profile-id <id> --threshold 5
+```
+
+`delta` flags drops greater than the threshold (default 5 points).
+
+### Approve a Buzz draft and schedule it
+
+```bash
+rankrush buzz drafts list --profile-id <id>
+rankrush buzz drafts approve --id <draft-uuid> --schedule-at 2026-05-15T09:00:00Z
+```
+
+### Create a lead account (admin)
+
+```bash
+rankrush leads create \
+  --business-name "Acme Co" \
+  --website-url https://acme.example \
+  --industry b2b_saas \
+  --location Berlin            # optional; used for local_service relevance
+# (you are prompted for the lead's email so it never lands in shell history)
+```
+
+Requires an **admin** `rr_live_*` api key — the backend verifies the caller's
+role. The command returns an invite (set-password) link to share with the lead
+plus a summary of the first-impression ChatGPT visibility scan. A 401/403
+means the key is not an admin key.
+
+---
+
+## Troubleshooting
+
+### `Authentication failed` / HTTP 401
+
+Your `RANKRUSH_API_KEY` is missing or invalid. Re-run:
+
+```bash
+rankrush init
+```
+
+The wizard validates the key against the backend before saving.
+
+### Network errors / timeouts
+
+Check your internet connection. The CLI talks to RankRush's Supabase backend over HTTPS — corporate proxies, VPNs with HTTPS inspection, and offline machines will all break it.
+
+### `Command failed with cryptic error`
+
+Add `--debug` before the command to see the full traceback:
+
+```bash
+rankrush --debug visibility check --profile-id <id>
+```
+
+Open an issue with that output at <https://github.com/nikolapevic/rankrush/issues>.
+
+### Want to verify your install end-to-end
+
+```bash
+rankrush --version           # → rankrush, version 0.1.15
+rankrush smoke               # → all edge functions green
+rankrush profiles list       # → at least one profile
+```
+
+If all three pass, you're set up correctly.
+
+---
+
+## Use it from an AI client (MCP)
+
+`pip install "rankrush-cli[mcp]"` also installs **`rankrush-mcp`**, a Model Context Protocol server that exposes these commands as tools so Claude Desktop / Claude Code / Cursor can drive RankRush directly. Setup + tool list: [docs/mcp.md](docs/mcp.md).
+
+## Versioning & changelog
+
+`rankrush-cli` follows [Semantic Versioning](https://semver.org/). Every release is recorded in [CHANGELOG.md](CHANGELOG.md); the versioning policy and release-cut checklist live in [docs/versioning.md](docs/versioning.md).
+
+## Contributing
+
+PRs and issues welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, test commands, and the PR checklist.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

rankrush_cli-0.1.37/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rankrush-cli"
+version = "0.1.37"
+description = "Agent-native CLI wrapper for the RankRush platform — wraps Supabase Edge Functions and REST API into structured, scriptable commands with --json output."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Gabriel Gircenko", email = "gabriel.gircenko@gmail.com" },
+]
+keywords = ["rankrush", "seo", "aeo", "ai-visibility", "cli", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "click>=8.1",
+    "requests>=2.31",
+    "python-dotenv>=1.0",
+    # Runtime deps of the vendored generated SDK (cli/rankrush_client, urllib3-based).
+    "urllib3>=2.1,<3",
+    "python-dateutil>=2.8.2",
+    "pydantic>=2.11",
+    "typing-extensions>=4.7.1",
+    # The generated urllib3 transport verifies SSL but ships no CA bundle; edge.py
+    # points it at certifi's, so certifi must be an explicit runtime dep.
+    "certifi>=2024.2.2",
+]
+
+[project.optional-dependencies]
+# `pip install rankrush-cli[mcp]` to also install the MCP server (rankrush-mcp).
+mcp = [
+    "mcp>=1.2",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock>=3.12",
+    "build>=1.0",
+    "coverage>=7.4",
+    "mcp>=1.2",
+]
+
+[project.scripts]
+rankrush = "rankrush.cli:cli"
+rankrush-mcp = "rankrush.mcp_server:main"
+
+[project.urls]
+Homepage = "https://rankrush.ai"
+Repository = "https://github.com/nikolapevic/rankrush"
+
+[tool.setuptools.packages.find]
+include = ["rankrush*"]
+exclude = ["tests*"]
+
+[tool.coverage.run]
+branch = true
+source = ["rankrush"]
+omit = [
+    "tests/*",
+    "*/tests/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]
+

rankrush_cli-0.1.37/rankrush/__init__.py

@@ -0,0 +1,3 @@
+"""RankRush CLI — agent-native wrapper for the RankRush Supabase backend."""
+
+__version__ = "0.1.37"