Track how visible your brand is when people ask ChatGPT — and outrank your competitors.
People are increasingly asking ChatGPT and other AI assistants things like "What's the best CRM software?" or "Which project management tool should I use?" — and your brand may or may not be showing up in those answers.
rankthebot is a command-line tool that:
- Runs hundreds of relevant queries against ChatGPT
- Detects which brands get mentioned — and in what position
- Scores your brand's LLM visibility from 0 to 100
- Shows you exactly which competitors are winning in AI responses
- Exports everything to CSV for easy analysis in Excel or Google Sheets
Understanding the process helps you get better results. Here is what happens under the hood when you run RankTheBot:
You start with a broad intent like "CRM software". RankTheBot generates dozens of realistic query variants by combining different personas (small business owner, developer, enterprise buyer, agency) and phrasings (best X for Y, X comparison, what X should I use). This simulates the wide range of ways real users ask ChatGPT about a topic.
For each query, RankTheBot sends it to ChatGPT (GPT-4o) and collects the response. Each query is run multiple times (default: 3) to account for the natural variability in LLM responses — the same question can produce different answers on different runs.
Each response is passed to a second AI model (GPT-4o-mini) that acts as a parser. It reads the response and extracts every brand mentioned, along with:
- Position — the order in which the brand was mentioned (1 = first)
- Sentiment — whether the mention was positive, neutral, negative, or qualified
- Context — the exact phrase where the brand appeared
All results are stored locally in a SQLite database on your machine.
The visibility score (0–100) is calculated from two signals:
- Mention rate — what percentage of runs included your brand
- Position weight — brands mentioned first score higher; position 1 keeps full weight, each subsequent position decays by ~18%
This means a brand that is mentioned in every response but always listed 5th scores lower than a brand mentioned in 80% of responses but always listed first.
Results are displayed as a ranked table in your terminal and can be exported to CSV for further analysis in Google Sheets or Excel.
You → define queries
↓
ChatGPT → generates responses
↓
GPT-4o-mini → extracts brand mentions
↓
SQLite → stores everything locally
↓
rankthebot → scores and ranks brands
- A Mac or Linux computer (Windows via WSL also works)
- Python 3.9 or higher (download here)
- An OpenAI API key (get one here)
Open your terminal and run:
python3 --versionYou should see Python 3.9.x or higher. If not, download Python here.
Clone the repository or download it as a ZIP:
git clone https://github.com/nikkos/rankthebot.git
cd rankthebotOr click here to download the ZIP, unzip it, and open your terminal in that folder.
Run this command inside the project folder:
pip3 install -e .After installation, you may need to add the install location to your PATH so you can run rankthebot from anywhere.
On Mac (zsh):
echo 'export PATH="$HOME/Library/Python/3.9/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcOn Linux:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrcrankthebot --helpYou should see the rankthebot command menu. You are ready to go!
Your OpenAI API key is stored locally on your machine only. It is saved in
~/.rankthebot/config.json— a hidden folder in your home directory, outside the project folder. This means it is never committed to Git or uploaded to GitHub.
Never share your ~/.rankthebot/config.json file with anyone.
If you accidentally expose your key, rotate it immediately.
rankthebot auth connect --openaiYou will be prompted to paste your API key. It is hidden while you type.
Add queries one by one:
rankthebot queries add "best CRM software"
rankthebot queries add "best project management tool"Or automatically generate dozens of variants from a single intent:
rankthebot queries expand "CRM software"This generates queries like:
- "best CRM software for small business owner"
- "CRM software comparison for enterprise buyer"
- "what CRM software should I use as a developer"
See all saved queries:
rankthebot queries listFirst, do a dry run to see how many API calls it will make (and estimate cost):
rankthebot scan --dry-runThen run the actual scan:
rankthebot scanBy default it runs 3 passes per query. You can change this:
rankthebot scan --runs 5Typical cost: ~$0.80–$1.50 for 65 queries x 3 runs using GPT-4o.
rankthebot report visibility --brand "hubspot"Example output:
Visibility Report - hubspot
┌──────────┬───────────────┬──────────────┬───────┐
│ LLM │ Mention Rate │ Avg Position │ Score │
├──────────┼───────────────┼──────────────┼───────┤
│ chatgpt │ 100.0% │ 1.91 │ 83.7 │
└──────────┴───────────────┴──────────────┴───────┘
Overall Score: 83.7/100
Save to CSV for Google Sheets or Excel:
rankthebot report visibility --brand "hubspot" --output visibility.csvrankthebot report competitorsExclude your own brand to focus on the competition:
rankthebot report competitors --exclude "hubspot"Save to CSV:
rankthebot report competitors --output competitors.csvExample output:
Top Competitors by LLM Visibility
┌────┬─────────────────────────┬───────────┬─────────────┬──────────────┬───────┐
│ # │ Brand │ Mention % │ Runs │ Avg Position │ Score │
├────┼─────────────────────────┼───────────┼─────────────┼──────────────┼───────┤
│ 1 │ HubSpot CRM │ 93.8% │ 183/195 │ 1.70 │ 82.0 │
│ 2 │ Zoho CRM │ 93.3% │ 182/195 │ 2.59 │ 66.6 │
│ 3 │ Pipedrive │ 66.7% │ 130/195 │ 4.22 │ 28.0 │
└────┴─────────────────────────┴───────────┴─────────────┴──────────────┴───────┘
The visibility score (0–100) combines two factors:
| Factor | What it measures |
|---|---|
| Mention rate | How often your brand appears across all queries |
| Avg position | How early in the response your brand is mentioned (position 1 = first) |
A brand mentioned in 100% of responses at position 1 scores 100/100. A brand mentioned in 50% of responses at position 5 scores much lower.
rankthebot auth connect --openai Connect your OpenAI API key
rankthebot queries add "query text" Add a single query
rankthebot queries expand "intent" Generate query variants from an intent
rankthebot queries list List all saved queries
rankthebot scan Run the scan
rankthebot scan --dry-run Estimate API calls without running
rankthebot scan --runs 5 Set number of runs per query (default: 3)
rankthebot report visibility --brand NAME Show your brand's visibility score
rankthebot report competitors Show top brands by LLM visibility
rankthebot report competitors --exclude NAME Exclude a brand (e.g. your own)
rankthebot report competitors --limit 10 Show top 10 only (default: 15)
All report commands support:
--output results.csv Save results to CSV file
After exporting, open the CSV directly in Google Sheets:
- Go to sheets.google.com
- Click File → Import
- Upload your CSV file
- Select "Comma" as the separator
MIT License — free to use, modify, and distribute.