rankrush-cli

Agent-native command-line interface for RankRush — 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: "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)

Install

pip install rankrush-cli

Requires Python 3.10, 3.11, or 3.12.

Developing locally (clone the repo first):

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:

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:

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:

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:

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:

# 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

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

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

# 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

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)

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:

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:

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

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.

Versioning & changelog

rankrush-cli follows Semantic Versioning. Every release is recorded in CHANGELOG.md; the versioning policy and release-cut checklist live in docs/versioning.md.

Contributing

PRs and issues welcome — see CONTRIBUTING.md for local setup, test commands, and the PR checklist.

License

MIT. See LICENSE.