April 1, 2026·4 min read

Run SEO Audits From the Terminal

The SEOLint CLI lets you audit any page without opening a browser. One command, structured output, LLM-ready fix prompts on every issue. Pipe it into scripts, feed it to Claude, or fail your CI build the moment an SEO regression appears.

Quick start

No global install needed. Set your API key and run:

export SEOLINT_API_KEY=sl_live_your_key_here

npx seolint scan https://mysite.com

Get your API key at seolint.dev/pricing. It's ready the moment you sign up.

What you get

The default output is a readable summary grouped by severity:

SEOLint: https://mysite.com
Scanned in 18s

CRITICAL (3 issues)
  ✗ Missing canonical URL
  ✗ No llms.txt found
  ✗ LCP is 4.8s (target: ≤ 2.5s)

WARNING (2 issues)
  ⚠ Meta description missing
  ⚠ Images missing alt text (4 images)

Run with --json for full output including fix prompts.

JSON output and fix prompts

Add --json to get machine-readable output. Every issue includes a fix_prompt field you can paste directly into Claude or Cursor:

npx seolint scan https://mysite.com --json | jq '.issues[0]'

{
  "id": "missing-canonical",
  "severity": "critical",
  "category": "seo",
  "title": "Missing canonical URL",
  "description": "No self-referencing canonical tag found in <head>.",
  "fix_prompt": "Add a self-referencing canonical tag to the <head> of this page:\n<link rel=\"canonical\" href=\"https://mysite.com/page-slug\" />"
}

Pipe fix prompts into Claude

Extract all critical fix prompts and pass them to Claude Code in one line:

# Get all critical fix prompts as a single block
npx seolint scan https://mysite.com --json \
  | jq -r '.issues[] | select(.severity=="critical") | "## " + .title + "\n" + .fix_prompt' \
  | claude "Apply each of these SEO fixes to the codebase. Commit each fix separately."

With the MCP server connected, you can skip the piping entirely and just ask Claude to scan and fix in one prompt. The CLI is for scripting contexts where you want direct control over the output.

Use in GitHub Actions

Fail a deploy if critical SEO issues are found:

name: SEO Check

on:
  push:
    branches: [main]

jobs:
  seo:
    runs-on: ubuntu-latest
    steps:
      - name: Scan site
        env:
          SEOLINT_API_KEY: ${{ secrets.SEOLINT_API_KEY }}
        run: |
          RESULT=$(npx seolint scan ${{ vars.SITE_URL }} --json)
          CRITICAL=$(echo $RESULT | jq '[.issues[] | select(.severity=="critical")] | length')
          echo "Critical issues found: $CRITICAL"
          if [ "$CRITICAL" -gt 0 ]; then
            echo "$RESULT" | jq -r '.issues[] | select(.severity=="critical") | "  - " + .title'
            exit 1
          fi

Add SEOLINT_API_KEYas a repository secret in Settings > Secrets.

CLI vs MCP server: which to use?

Context	Use this
Asking Claude to scan in a conversation	MCP server
Scripting and automation	CLI
GitHub Actions	CLI
Piping into jq or other tools	CLI
Asking Claude to fix your codebase	MCP server (or both)
Quick one-off check in the terminal	CLI

Both use the same underlying API and return the same structured output. The package is seolint-mcp on npm, and it knows which mode to run based on how it's invoked.

All CLI flags

Flag	Description
`--json`	Output raw JSON (includes fix_prompt on every issue)
`--severity critical`	Filter output to critical issues only
`--category seo`	Filter to one category: seo, performance, accessibility, aeo
`--no-color`	Disable color output (useful in CI logs)
`--quiet`	Only exit code, no output (0 = clean, 1 = issues found)

FAQ

Do I need to install anything to use the CLI?

No. The CLI runs via npx, so you only need Node.js. Run npx seolint scan <url> and it fetches the package automatically. Nothing to install globally.

What does the CLI output?

By default it prints a formatted summary to stdout. Add --json for raw JSON (ideal for piping into jq or other tools). The JSON includes issue title, severity, category, and a fix_prompt field you can paste into Claude or Cursor.

Can I use the CLI in GitHub Actions?

Yes. Set SEOLINT_API_KEY as a secret, run npx seolint scan <url> --json, parse the output with jq, and fail the build if critical issues are found. Full example in the guide below.

Is the CLI the same as the MCP server?

Yes. The seolint-mcp npm package serves two purposes: when you configure it in Claude Desktop or Claude Code it acts as an MCP server. When you run it as npx seolint scan <url> it acts as a CLI tool. Same package, same API, two interfaces.

Start scanning from the terminal

API key ready instantly. Works with npx, GitHub Actions, and Claude.

Get API key →Set up MCP server instead