GEO Audit CLI

Analyze brand visibility in AI search engines (ChatGPT, Perplexity)

GEO (Generative Engine Optimization) Audit shows how AI-powered search engines see your brand compared to competitors. Essential for modern digital marketing strategy.

Features

• 🔍 Multi-provider analysis — ChatGPT (OpenAI) + Perplexity
• 📊 Automatic query generation — relevant search queries based on brand/category
• 🎯 Position tracking — where you rank in AI recommendations
• 💬 Sentiment analysis — how AI describes your brand
• 🏆 Competitive comparison — score vs competitors
• 📝 Multiple report formats — Terminal, HTML, JSON

Installation

cd ~/clawd/projects/geo-tool/cli
npm install
npm run build
npm link  # Makes 'geo-audit' available globally

API Keys

Set environment variables before use:

export OPENAI_API_KEY="sk-..."
export PERPLEXITY_API_KEY="pplx-..."

Get API keys:

• OpenAI: https://platform.openai.com/api-keys
• Perplexity: https://www.perplexity.ai/settings/api

Works without keys — graceful degradation with instructions.

Usage

Basic Audit

# Audit a brand with competitors
geo-audit "Notion" --competitors "Asana,Monday,ClickUp"

# Audit with category (generates relevant queries)
geo-audit "Notion" --competitors "Asana,Monday" --category "project management"

# Custom search query
geo-audit --query "best project management tools 2024"

Output Options

# Save HTML report (shareable)
geo-audit "Notion" -c "Asana,Monday" --html report.html

# Save JSON report (for processing)
geo-audit "Notion" -c "Asana,Monday" --json report.json

# Include raw AI responses
geo-audit "Notion" -c "Asana,Monday" --json report.json --raw

Configuration

# Use specific providers
geo-audit "Notion" --providers "openai,perplexity"
geo-audit "Notion" --providers "openai"

# Control number of queries
geo-audit "Notion" -c "Asana" -n 10

# Check API status
geo-audit status

Example Output

╔═══════════════════════════════════════════════════════════════╗
║                    📊 GEO AUDIT REPORT                        ║
╚═══════════════════════════════════════════════════════════════╝

  Brand: Notion
  Competitors: Asana, Monday, ClickUp
  Date: 2024-02-18

═══ Query Results ════════════════════════════════════════════════

  🔍 "best project management tools"

  🤖 ChatGPT:
     ├── Position: #2
     ├── Sentiment: Positive 👍
     └── "Notion is excellent for teams that need flexibility..."

  🔮 Perplexity:
     ├── Position: #1
     ├── Sentiment: Positive 👍
     └── "Notion leads the pack with its all-in-one workspace..."

═══ Competitive Analysis ═════════════════════════════════════════

┌──────────────────┬──────────┬───────────┬──────────┐
│ Brand            │ ChatGPT  │ Perplexity│ Score    │
├──────────────────┼──────────┼───────────┼──────────┤
│ Notion (you)     │ 🥈 #2    │ 🥇 #1     │ 92/100   │
│ Asana            │ 🥇 #1    │ 🥈 #2     │ 90/100   │
│ Monday           │ 🥉 #3    │ #4        │ 65/100   │
│ ClickUp          │ #4       │ 🥉 #3     │ 60/100   │
└──────────────────┴──────────┴───────────┴──────────┘

═══ Summary ══════════════════════════════════════════════════════

  🟢 Overall Visibility: HIGH
  📊 Average Score: 92/100
  📍 Positions: ChatGPT: #2 | Perplexity: #1
  🏆 Rank: #1 of 4 brands

═══ Recommendations ══════════════════════════════════════════════

  1. 📈 Position #2 in ChatGPT — aim for top 1 with more differentiators
  2. 📊 Asana ties with you — analyze their content strategy

How It Works

1. Query Generation — Creates relevant search queries:

   • "best [category] software"
   • "[brand] vs [competitor]"
   • "alternatives to [competitor]"
   • "[brand] review"

2. AI Querying — Sends queries to:

   • OpenAI GPT-4 (simulates ChatGPT)
   • Perplexity API (real Perplexity responses)

3. Response Parsing — Extracts:

   • Brand mentions and positions
   • Sentiment (positive/neutral/negative)
   • Context quotes

4. Scoring — Calculates:

   • Position-based score (0-100)
   • Sentiment modifiers
   • Overall visibility rating

5. Report Generation — Outputs:

   • Terminal report with colors
   • HTML report for sharing
   • JSON for further processing

Scoring System

| Position | Base Score | |----------|------------| | #1 | 100 | | #2 | 85 | | #3 | 70 | | #4 | 55 | | #5 | 45 | | Mentioned (no position) | 10 | | Not mentioned | 0 |

Sentiment Modifiers:

• Positive: ×1.2
• Neutral: ×1.0
• Negative: ×0.7

Project Structure

cli/
├── src/
│   ├── index.ts              — CLI entry point
│   ├── queries/
│   │   └── generator.ts      — Query generation
│   ├── providers/
│   │   ├── types.ts          — TypeScript interfaces
│   │   ├── openai.ts         — OpenAI API client
│   │   └── perplexity.ts     — Perplexity API client
│   ├── analysis/
│   │   ├── parser.ts         — Response parsing
│   │   ├── scorer.ts         — Scoring logic
│   │   └── comparator.ts     — Competitive analysis
│   └── report/
│       ├── terminal.ts       — CLI output
│       ├── html.ts           — HTML reports
│       └── json.ts           — JSON export
├── package.json
├── tsconfig.json
└── README.md

Development

# Build
npm run build

# Run without building
npm run dev

# Clean build artifacts
npm run clean

Tips

1. Start with competitors — Comparing against known brands gives better context
2. Use category — Helps generate more relevant queries
3. Check regularly — AI responses change as models are updated
4. Save HTML reports — Great for sharing with marketing team
5. Use JSON for tracking — Monitor visibility over time

License

MIT