Run SEO Audits From the Terminal: The SEOLint CLI

Quick start

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

export SEOLINT_API_KEY=sl_live_your_key_here

npx @randomcode-seolint/cli 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 @randomcode-seolint/cli 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 @randomcode-seolint/cli 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, including Core Web Vitals thresholds surfaced from the PSI API.

Use in GitHub Actions

Fail a deploy if critical SEO issues are found. This is a standard GitHub Actions workflow, no special runners required:

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 @randomcode-seolint/cli 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 @randomcode-seolint/cli 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 @randomcode-seolint/cli 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?

They are separate npm packages that use the same SEOLint API. The MCP server (seolint-mcp) connects to Claude Desktop and Claude Code. The CLI (@randomcode-seolint/cli) runs scans from the terminal. Both produce the same audit output.

Start scanning from the terminal

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

Get API key →Set up MCP server instead