rankforge-cli

rankforge-cli

Technical SEO + AI-search readiness for your site — measured, not guessed. Run it in your terminal, let your AI editor use it as an agent, or gate your CI with it. No AI required, no API key, no account, nothing phones home.

npx rankforge-cli audit https://your-site.com

RankForge audit  https://your-site.com/
8 pages · 3.1s · deterministic — no AI, no external API

Score  87/100
  metadata          ███████████░   93
  indexing          █████████░░░   76
  images            ████████████  100
  internal-linking  ██████████░░   86
  …
Issues (8)
  CRITICAL Pages set to noindex (1)                     → /pricing
  MEDIUM   Pages missing a canonical URL (2) · fix template
  MEDIUM   Missing internal links between related pages (8)

AI search readiness  64/100  4 things to improve, run: rankforge geo https://your-site.com/

Contents

1. In your terminal — 30 seconds, nothing to install
2. In your AI editor (the agent) — Claude Code, Cursor, VS Code, Windsurf, Claude Desktop
3. In your CI — fail a PR when SEO regresses
4. In your browser — no install at all
5. What it checks · AI-search readiness (GEO) · Commands · Troubleshooting

Requires Node.js 18+ (check with node -v). Works on macOS, Linux and Windows — CI runs every commit on all three.

1. In your terminal

npx rankforge-cli audit https://your-site.com        # full audit
npx rankforge-cli audit http://localhost:3000        # your dev server, before you deploy
npx rankforge-cli geo https://your-site.com          # can ChatGPT / Claude / Perplexity cite you?
npx rankforge-cli llms https://your-site.com --out public/llms.txt   # generate llms.txt
npx rankforge-cli audit https://your-site.com --html report.html     # shareable report

npx downloads and runs the latest version each time. Using it a lot? Install it once and drop the npx:

npm install -g rankforge-cli
rankforge audit https://your-site.com

Fix what it finds. Mechanical issues come with a ready, framework-idiomatic patch:

rankforge fix framework-robots-missing --framework nextjs
rankforge fix indexing-canonical-missing --framework astro --url https://your-site.com

2. In your AI editor (the agent)

This is where RankForge is most useful: your coding assistant gets RankForge's tools over MCP, audits your site (including localhost), and edits the files in your repo to fix what it finds. RankForge measures; your assistant reasons and writes the code.

It runs locally — no server, no account, no key.

Claude Code

claude mcp add rankforge -- npx -y rankforge-cli mcp

Windows (native, not WSL): claude mcp add rankforge -- cmd /c npx -y rankforge-cli mcp

Check it: claude mcp list should show rankforge … ✓ Connected.

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this project):

{
  "mcpServers": {
    "rankforge": { "command": "npx", "args": ["-y", "rankforge-cli", "mcp"] }
  }
}

VS Code (Copilot agent mode)

.vscode/mcp.json:

{
  "servers": {
    "rankforge": { "type": "stdio", "command": "npx", "args": ["-y", "rankforge-cli", "mcp"] }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "rankforge": { "command": "npx", "args": ["-y", "rankforge-cli", "mcp"] }
  }
}

Claude Desktop

Settings → Developer → Edit Config (claude_desktop_config.json):

{
  "mcpServers": {
    "rankforge": { "command": "npx", "args": ["-y", "rankforge-cli", "mcp"] }
  }
}

Windows: use "command": "cmd", "args": ["/c", "npx", "-y", "rankforge-cli", "mcp"], then restart the app.

Then just ask

"Use rankforge to audit http://localhost:3000 and fix everything you can."

"Check whether AI search engines can cite my site, and fix what blocks them."

"Generate an llms.txt for my site and add it to the public folder."

The tools your assistant gets

3. In your CI (GitHub Action)

Fail a pull request when the score drops, and keep the HTML report as an artifact:

# .github/workflows/seo.yml
name: SEO
on: [pull_request]
jobs:
  seo:
    runs-on: ubuntu-latest
    steps:
      - uses: Barbudda/rankforge-cli@v0.2.0
        with:
          url: https://staging.your-site.com   # a deployed preview/staging URL
          fail-under: 80                       # technical SEO gate
          geo-fail-under: 60                   # AI-search readiness gate (optional)
          report: rankforge-report.html
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: seo-report
          path: rankforge-report.html

Or without the Action, in any CI: npx rankforge-cli audit "$URL" --fail-under 80 (exit code 1 below the threshold).

4. In your browser

No install: rank-forge-blue.vercel.app/audit runs the same engine on 3 pages of any public URL, free, no signup.

What it checks

~35 deterministic checks in 8 categories. Every finding cites evidence from the page — nothing is inferred by a model.

• Metadata — missing/duplicate titles and descriptions, length, OpenGraph & Twitter cards
• Indexing — canonicals (missing or pointing elsewhere), accidental noindex, <html lang>, redirect chains, near-duplicate pages
• Structure — H1s, skipped heading levels, thin pages, readability, keyword stuffing, title ↔ content alignment
• Images — alt text, dimensions (layout shift), lazy-loading, real byte weights and legacy formats (fetched, not guessed)
• Structured data — missing JSON-LD, schema.org blocks missing required properties
• Internal linking — orphan pages, click depth, broken links (real HTTP status), generic anchors, related pages that should link to each other
• Performance — server response time, render-blocking resources, oversized HTML, mixed content
• Framework — robots.txt / sitemap presence and conventions for Next.js, Nuxt, Astro, SvelteKit, Remix, Vite, MDX and static sites

AI-search readiness (GEO)

Answer engines (ChatGPT search, Claude, Perplexity, Gemini, Copilot) can only cite a page they're allowed to fetch, can read without running JavaScript, and can extract a clear answer from. rankforge geo checks all three:

Honest limit: this measures what you control. Whether an engine ends up citing you depends on the engine — nobody outside them can measure or promise that.

Commands

Troubleshooting

• node: command not found / version errors — install Node 18+ from nodejs.org.
• Windows: the editor says the MCP server failed to start — use the cmd /c npx … form shown above; editors can't launch npx directly on Windows.
• "Couldn't reach that site" — the URL must answer over http(s) from your machine. For local sites, start your dev server first.
• CI can't audit localhost — CI runners can't see your laptop. Audit a deployed preview or staging URL there.
• It doesn't report backlinks / rankings / search volume — by design. Those need data only search engines and paid indexes have; RankForge sticks to what can be measured from your site.
• A finding is wrong on your site — that's a bug: please open an issue with the URL.

Develop

git clone https://github.com/Barbudda/rankforge-cli && cd rankforge-cli
npm install
npm test          # builds, then runs the end-to-end suite against a local fixture site
node dist/index.js audit https://example.com

The engine lives in src/lib/audit (rules, link graph, content analysis, GEO, fix templates); the CLI in cli/src.

License

MIT