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