RankCLI documentation

Installation

npm works everywhere Node does. Homebrew and Scoop install a standalone binary instead — no Node required.

npx @rankcli/cli audit -u https://your-site.dev

Also available via yarn global add @rankcli/cli or pnpm add -g @rankcli/cli.

Verify the installation:

rankcli --version

Authentication

Link your CLI to your RankCLI account to unlock full features:

rankcli login

This will prompt for email and password. You can also use browser-based login:

rankcli login --browser

Or provide your email directly:

rankcli login --email you@example.com

API Key Authentication (CI/CD)

For non-interactive environments like CI/CD pipelines, use an API key:

rankcli login --token rankcli_your_api_key_here

Or set the environment variable (recommended for CI):

export RANKCLI_API_KEY=rankcli_your_api_key_here

Generate an API key from Account Settings → API Keys.

Check your login status:

rankcli whoami

Feature Comparison

Running Your First Audit

Run a comprehensive SEO audit on any URL:

rankcli audit --url https://yoursite.com

What Gets Checked

The audit runs 280+ SEO checks across these categories:

Multi-Page Audits

Audit multiple pages at once to find site-wide issues:

rankcli audit --url https://yoursite.com --max-pages 10

AI-Powered Analysis

Enable AI analysis for content suggestions and prioritized fixes:

rankcli audit --url https://yoursite.com --ai

Runs on your own provider, never RankCLI's: Apple Intelligence on a Mac that has it, otherwise the first key it finds (OPENROUTER_API_KEY, OPENAI_API_KEY, ...) or a local Ollama. Choose one with --ai-provider.

What is GEO?

Generative Engine Optimization (GEO) is SEO for AI-powered search engines. As users shift from traditional search to AI assistants, your content needs to be optimized for how LLMs discover, understand, and cite information.

Traditional SEO vs GEO

AI Crawlers

RankCLI tracks access for all major AI crawlers:

Using rankcli geo

Run a GEO analysis on any URL:

rankcli geo --url https://yoursite.com

What Gets Analyzed

JSON Output for CI

rankcli geo --url https://yoursite.com --output json

GEO Optimization Tips

User-agent: GPTBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: PerplexityBot
Allow: /

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [...]
}
</script>

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools. RankCLI's MCP server gives AI assistants direct access to SEO analysis capabilities.

Use Cases

• Ask Claude to audit a URL during code review
• Generate robots.txt or structured data on demand
• Check AI crawler visibility while building
• Automate SEO checks in AI-powered workflows

Setup

The MCP server is free, local, and requires no signup — nothing is sent to RankCLI's servers. For centralized dashboard sync across a team, a hosted option is also available below.

One-click install

Nothing to configure and no account. The editor writes the config for you.

Claude Desktop

Download the latest .mcpb extension and double-click it. No config file, no terminal.

Claude Code

One line, no config file:

claude mcp add rankcli -- npx -y @rankcli/mcp-server

Claude Desktop Setup

Add RankCLI to your Claude Desktop configuration:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "rankcli": {
      "command": "npx",
      "args": ["@rankcli/mcp-server"]
    }
  }
}

Windows

Edit %APPDATA%\\Claude\\claude_desktop_config.json:

{
  "mcpServers": {
    "rankcli": {
      "command": "npx",
      "args": ["@rankcli/mcp-server"]
    }
  }
}

Alternative: Free Hosted (no install)

Skip the local install entirely — point at the free hosted endpoint instead:

{
  "mcpServers": {
    "rankcli": {
      "url": "https://mcp.rankcli.dev/mcp/free"
    }
  }
}

Alternative: Hosted (for team dashboard sync)

Get a free API key from Account → API Keys, then point at the hosted endpoint instead:

{
  "mcpServers": {
    "rankcli-hosted": {
      "url": "https://mcp.rankcli.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Available Tools

The MCP server provides 15 tools:

Example Prompts

Authentication Commands

Manage your RankCLI authentication.

rankcli login [options]

Options:
  -e, --email <email>    Email address for login
  -b, --browser          Open browser for OAuth login
  -t, --token <apiKey>   API key for non-interactive auth (CI/CD)

rankcli logout              Log out of your account
rankcli whoami              Show current logged in user

Examples

# Interactive login (email/password)

rankcli login

# Login with API key (CI/CD)

rankcli login --token rankcli_your_api_key_here

# Or set environment variable

export RANKCLI_API_KEY=rankcli_your_api_key_here

rankcli audit

Run a comprehensive SEO audit on a URL or local project.

rankcli audit [options]

Options:
  -u, --url <url>           URL to audit
  -o, --output <format>     Output format (json, console) (default: console)
  --max-pages <n>           Max pages to crawl (default: 5)
  --check-links             Check for broken internal/external links (slower)
  --fail-on <level>         CI gate: exit 1 on any issue at or above error, warning or notice
  --min-score <n>           CI gate: exit 1 if the score is below n
  --ai                      AI analysis on your own provider (Apple Intelligence on a
                            Mac that has it; otherwise your key or a local model)
  --ai-provider <provider>  apple, openrouter, openai, anthropic, groq, gemini, deepseek,
                            mistral, cerebras, together, fireworks, ollama, lmstudio,
                            llamacpp, vllm, custom (or set RANKCLI_AI_PROVIDER)
  --ai-key <key>            Provider API key (or its env var, e.g. OPENROUTER_API_KEY)
  --ai-model <model>        Override the provider's default model
  --ai-base-url <url>       Any OpenAI-compatible server (implies --ai-provider custom)

Examples

# Basic audit

rankcli audit --url https://example.com

# Multi-page audit with JSON output

rankcli audit --url https://example.com --max-pages 10 -o json > report.json

# AI-enhanced audit

rankcli audit --url https://example.com --ai

rankcli fix

Agentic SEO fixer - automatically detect issues, generate fixes, apply them, commit, and push. Full CI/CD automation.

rankcli fix [options]

Options:
  -u, --url <url>         URL to analyze
  --auto                  Auto-apply fixes without confirmation
  --commit                Commit changes with conventional commit message
  --push                  Push changes after committing (requires --commit)
  --dry-run               Preview changes without applying
  --only <codes>          Fix only specific issue codes (comma-separated)
  -o, --output <format>   Output format (text, json)

Examples

# Preview fixes without applying

rankcli fix --url https://mysite.com --dry-run

# Fix, commit, and push (CI mode)

rankcli fix --url https://mysite.com --auto --commit --push

# Fix only specific issues

rankcli fix --url https://mysite.com --auto --only TITLE_MISSING,META_DESC_MISSING

rankcli track

Keyword rank tracking - monitor your SERP positions over time.

rankcli track <command> [options]

Commands:
  add <keywords...>        Add keywords to track
  status                   Show current keyword rankings
  history                  Show keyword position history
  check                    Check current rankings (calls SERP API)
  export                   Export tracking data

Common Options:
  -u, --url <url>          URL to track rankings for
  -o, --output <format>    Output format (text, json)

Examples

# Add keywords to track

rankcli track add "seo tool" "cli seo" --url https://mysite.com

# View current rankings

rankcli track status --url https://mysite.com

# Check live SERP positions

rankcli track check --url https://mysite.com

# View position history for a keyword

rankcli track history --keyword "seo tool" --url https://mysite.com --days 30

# Export as CSV

rankcli track export --url https://mysite.com --format csv > rankings.csv

rankcli apply

Generate and apply SEO fixes to your local codebase. Detects your framework and generates appropriate fixes.

rankcli apply [options]

Options:
  -u, --url <url>        URL to analyze for fixes
  --dry-run              Preview changes without applying
  --auto                 Apply all fixes without confirmation

Examples

# Preview fixes without applying

rankcli apply --url https://mysite.com --dry-run

# Apply fixes with confirmation

rankcli apply --url https://mysite.com

# Auto-apply all fixes (CI mode)

rankcli apply --url https://mysite.com --auto

rankcli keywords

AI-powered keyword research and analysis.

rankcli keywords [options]

Options:
  -u, --url <url>            URL to analyze
  -s, --seed <keywords>      Seed keywords (comma-separated)
  --auto                     Auto-extract seed keywords from your page
  --quick                    Quick mode - skip questions, use defaults
  --ai                       AI research on your own provider (as audit --ai)
  --ai-provider <provider>   apple, openrouter, openai, ollama, ... (or RANKCLI_AI_PROVIDER)
  --ai-key / --ai-model / --ai-base-url   as for audit
  --competitor               Competitor gap analysis mode
  -c, --competitors <urls>   Competitor domains (comma-separated)

Examples

# AI-powered keyword research

rankcli keywords --url https://mysite.com --ai

# Quick analysis with seed keywords

rankcli keywords --url https://mysite.com --quick -s 'seo tools,seo audit'

# Competitor gap analysis

rankcli keywords --url https://mysite.com --competitor -c 'competitor1.com,competitor2.com' -s 'target keyword'

rankcli content

Analyze content for readability, keyword density, and featured snippet optimization.

rankcli content [options]

Options:
  -u, --url <url>          URL to analyze
  -k, --keyword <keyword>  Target keyword for analysis
  --headline <headline>    Analyze a headline
  --mode <mode>            Analysis mode (full, readability, headline, snippet, density)

Examples

# Full content analysis

rankcli content --url https://mysite.com/blog-post --keyword 'seo tips'

# Check headline effectiveness

rankcli content --headline 'The Ultimate Guide to SEO'

rankcli intent

Classify search intent for a keyword.

rankcli intent <keyword>

Arguments:
  keyword     Keyword to analyze for search intent

Examples

rankcli intent 'buy running shoes'

rankcli intent 'how to optimize images for seo'

rankcli setup

Configure tracking and CI/CD integrations.

rankcli setup [options]

Options:
  --ga4 <id>        Google Analytics 4 Measurement ID (G-XXXXXXXXXX)
  --gsc <code>      Google Search Console verification code
  --github-action   Set up automated GitHub Action
  --schedule <freq> GitHub Action schedule (daily, weekly, monthly)
  --all             Interactive setup wizard

Examples

# Add GA4 tracking to your project

rankcli setup --ga4 G-XXXXXXXXXX

# Create GitHub Actions workflow

rankcli setup --github-action

# Interactive setup wizard

rankcli setup --all

rankcli gsc-setup

Show Google Search Console API setup instructions.

rankcli gsc-setup

Managing Projects

Projects represent websites you want to audit. Each project tracks:

• Your website URL and domain
• Detected framework (React, Next.js, Vue, etc.)
• GitHub repository connection
• Audit history and scores over time
• All discovered SEO issues

Creating a Project

Understanding Audits

Each audit runs 280+ SEO checks and produces a comprehensive report.

Health Scores

Your overall score is calculated from category scores:

Score Interpretation

Managing Issues

Issues are SEO problems discovered during audits. Each issue includes:

• Severity - Error (critical), Warning, or Notice
• Category - Which SEO area is affected
• Description - What the problem is
• Impact - How it affects your SEO
• How to Fix - Step-by-step fix instructions
• Affected URLs - Which pages have this issue

Issue Actions

Bulk Actions

Select multiple issues using the checkboxes, then use the floating action bar to:

• Mark multiple issues as ignored
• Mark multiple issues as won't fix
• Create a single PR for all selected issues

Exporting Reports

Export your audit results in various formats:

Installing the GitHub App

The RankCLI GitHub App needs to be installed on your repository to enable integrations.

Route Discovery

When connected to GitHub, RankCLI can discover your routes from your source code instead of just crawling links. This finds pages that aren't linked from the homepage.

Supported Frameworks

Automatic Fix PRs

Create pull requests with AI-generated fixes for your SEO issues.

What Gets Fixed

The AI generates fixes for issues that can be automatically resolved:

• Missing or incomplete meta tags (title, description, OG)
• Missing robots.txt or sitemap.xml
• Missing security headers (_headers, vercel.json)
• Missing structured data (JSON-LD)
• Framework-specific optimizations (Next.js Metadata API, etc.)

Automatic Triggers

Once connected, RankCLI automatically responds to GitHub events:

Supported Frameworks

We support the most popular web frameworks with specific SEO guidance:

How Detection Works

RankCLI detects your framework using multiple signals:

Framework Recipes

Each framework has a "recipe" containing specialized SEO guidance:

• Framework-specific checks - Issues unique to your framework
• SEO strengths - Built-in SEO features to leverage
• SEO challenges - Common pitfalls to avoid (e.g., CSR issues)
• Performance tips - Framework-specific optimizations
• Recommended packages - Best plugins/gems for SEO
• Migration paths - How to fix CSR issues with SSR

Local Workflow (Solo Plan)

Keep full control over your repository. No GitHub access required.

rankcli audit --url https://yoursite.com

rankcli apply --url https://yoursite.com --dry-run

rankcli apply --url https://yoursite.com

git add . && git commit -m 'fix(seo): apply SEO fixes'

git push origin main

GitHub Workflow (Pro Plan)

Full automation with GitHub integration. PRs created automatically from the dashboard or CLI.

rankcli audit --url https://yoursite.com

rankcli fix --pr

CI/CD Integration

Run SEO audits as part of your CI/CD pipeline to catch issues before deployment.

GitHub Actions

name: SEO Audit
on:
  push:
    branches: [main]
  pull_request:

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install RankCLI
        run: npm install -g @rankcli/cli

      - name: Run SEO Audit
        run: rankcli audit --url ${{ secrets.SITE_URL }} -o json > audit.json
        env:
          RANKCLI_API_KEY: ${{ secrets.RANKCLI_API_KEY }}

      - name: Check for critical issues
        run: |
          errors=$(jq '.issues | map(select(.severity == "error")) | length' audit.json)
          if [ "$errors" -gt 0 ]; then
            echo "::error::Found $errors critical SEO issues"
            exit 1
          fi

Using the GitHub Action

Alternatively, use our official GitHub Action:

- uses: integrallis/rankcli-action@v1
  with:
    url: ${{ secrets.SITE_URL }}
    api-key: ${{ secrets.RANKCLI_API_KEY }}
    fail-on-errors: true

REST API

The RankCLI API allows you to run audits programmatically and integrate SEO checks into your own tools and workflows.

Authentication

Use your API key in the X-API-Key header:

curl -X POST https://api.rankcli.dev/v1/audit \
  -H "X-API-Key: rankcli_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Generate an API key from Account Settings → API Keys. API keys start with rankcli_.

Endpoints

{
  "url": "https://example.com",
  "maxPages": 5,
  "enableAI": true
}

Webhooks

Receive notifications when audits complete or issues are found.

Available Events

Payload Example

{
  "event": "audit.completed",
  "project_id": "proj_xxx",
  "audit_id": "audit_xxx",
  "score": 85,
  "issues_found": 12,
  "issues_by_severity": {
    "error": 2,
    "warning": 6,
    "notice": 4
  },
  "timestamp": "2024-01-15T10:30:00Z"
}