SEOmator Audit

A comprehensive SEO audit tool with 251 audit rules across 20 categories. Available as both a command-line tool and an Electron desktop app. Analyze any website for SEO best practices, Core Web Vitals, security headers, structured data, accessibility, JavaScript rendering, redirect chains, and more.

Prefer a web interface? Try our Free SEO Audit Tool for a visual, browser-based SEO analysis.

Features

• 251 SEO Audit Rules across 20 categories
• Desktop App - Visual audit dashboard with real-time progress, interactive results, score history, and light/dark theme
• CLI Tool - Single page & crawl mode with 5 output formats
• Core Web Vitals - LCP, CLS, FCP, TTFB, INP measurement via Playwright
• JavaScript Rendering Analysis - Compare raw vs rendered DOM for SPA/CSR sites
• 5 Output Formats - Console, JSON, HTML, Markdown, and LLM-optimized XML
• AI/GEO Readiness - Check semantic HTML, AI bot access, and llms.txt
• Redirect Chain Detection - Loops, broken redirects, meta/JS redirects
• HTML Validation - Doctype, charset, head structure, lorem ipsum detection
• Cross-Page Analysis - Duplicate content detection, orphan pages, pagination
• Concurrent Crawling - Fast multi-page audits with configurable concurrency
• SQLite Storage - Persistent crawl data with compression and audit history
• CI/CD Ready - Exit codes, JSON output, GitHub Actions & GitLab CI examples
• TOML Configuration - Project-level settings with presets and inheritance

Installation

From npm (recommended)

# Install globally
npm install -g @seomator/seo-audit

# Run audit
seomator audit https://example.com

Note: The CLI automatically uses your system Chrome, Chromium, or Edge browser for Core Web Vitals measurement. No additional browser installation is required if you have Chrome installed.

From source

git clone https://github.com/seo-skills/seo-audit-skill.git
cd seo-audit-skill
npm install
npm run build

# Run directly
./dist/cli.js audit https://example.com

# Or link globally
npm link
seomator audit https://example.com

Desktop App

The desktop app provides a visual audit dashboard with real-time progress streaming, interactive results, score history, and light/dark theme support.

Running

# From source
git clone https://github.com/seo-skills/seo-audit-skill.git
cd seo-audit-skill
npm install
npx electron-rebuild -f -w better-sqlite3   # Compile native module for Electron
npm run electron:dev                          # Launch with hot reload

Building

npm run electron:build    # Production build
npm run electron:pack     # Build + package distributable

Desktop App Features

• Real-time progress - Live category-by-category progress as the audit runs
• Score dashboard - Overall score circle, category grid, and issues summary table
• Interactive results - Expandable rule cards with rule descriptions, affected items, page URL badges, and inline fix suggestions
• Filter & navigate - Filter by status (All/Failures/Warnings/Passed), click issues to jump to details
• Score history - Track audit scores over time per domain with trend charts
• Light/dark theme - Follows your system preference or toggle manually

Quick Start (CLI)

# Basic audit
seomator audit https://example.com

# Skip Core Web Vitals (faster)
seomator audit https://example.com --no-cwv

# Audit specific categories
seomator audit https://example.com -c core,security,perf

# JSON output (for CI/CD or parsing)
seomator audit https://example.com --format json

# HTML report
seomator audit https://example.com --format html -o report.html

# LLM-optimized output (pipe to Claude)
seomator audit https://example.com --format llm --no-cwv | claude "analyze and prioritize fixes"

# Crawl multiple pages
seomator audit https://example.com --crawl --max-pages 20

# Full options
seomator audit https://example.com --crawl -m 50 --concurrency 5 --timeout 60000 --format json -o results.json

Commands

seomator audit <url>

Run SEO audit on a URL.

seomator init

Create a seomator.toml config file.

seomator init                    # Interactive setup
seomator init -y                 # Use defaults
seomator init --preset blog      # Blog preset
seomator init --preset ecommerce # E-commerce preset
seomator init --preset ci        # Minimal CI config

seomator crawl <url>

Crawl website without running analysis. Saves data for later analysis with seomator analyze.

seomator crawl https://example.com -m 20
seomator crawl https://example.com --refresh
seomator crawl https://example.com --resume

seomator analyze [crawl-id]

Run rules on stored crawl data.

seomator analyze                           # Analyze latest crawl
seomator analyze --latest --save           # Analyze and save
seomator analyze 2026-01-23-abc123         # Specific crawl

seomator report [query]

View and query past reports.

seomator report --list                     # List all reports
seomator report --project mysite           # Filter by project

seomator config [key] [value]

View or modify configuration.

seomator config --list                     # Show all config
seomator config crawler.max_pages 50       # Set value
seomator config validate                   # Validate config

seomator db

Database management.

seomator db migrate              # Migrate JSON to SQLite
seomator db migrate --dry-run    # Preview migration
seomator db stats -v             # Database statistics
seomator db restore              # Rollback migration

seomator self doctor

Check system setup and dependencies.

seomator self doctor -v          # Verbose diagnostics

Exit Codes

Categories & Rules (251 total)

Core (19 rules) - 12% weight

Performance (22 rules) - 12% weight

Links (19 rules) - 8% weight

Images (14 rules) - 8% weight

Security (16 rules) - 8% weight

Technical SEO (13 rules) - 7% weight

Crawlability (18 rules) - 5% weight

Structured Data (13 rules) - 5% weight

JavaScript Rendering (13 rules) - 5% weight

Accessibility (12 rules) - 4% weight

Content (17 rules) - 5% weight

Social (9 rules) - 3% weight

E-E-A-T (14 rules) - 3% weight

URL Structure (14 rules) - 3% weight

Redirects (8 rules) - 3% weight

Mobile (5 rules) - 2% weight

Internationalization (10 rules) - 2% weight

HTML Validation (9 rules) - 2% weight

AI/GEO Readiness (5 rules) - 2% weight

Legal Compliance (1 rule) - 1% weight

Configuration

Create a seomator.toml config file with seomator init:

[project]
name = "my-website"
domains = ["example.com", "www.example.com"]

[crawler]
max_pages = 100
concurrency = 3
timeout_ms = 30000
respect_robots = true
delay_ms = 100
include = []
exclude = ["/admin/**", "/api/**"]
drop_query_prefixes = ["utm_", "gclid", "fbclid"]

[rules]
enable = ["*"]
disable = ["perf-inp"]  # Supports wildcards: "core-*"

[output]
format = "console"  # console, json, html, markdown, llm

Config priority (highest to lowest):

1. CLI arguments
2. Local ./seomator.toml
3. Parent directory configs
4. Global ~/.seomator/config.toml
5. Built-in defaults

Output Formats

Terminal Output

╔══════════════════════════════════════════════════════════════╗
║  SEOmator Audit Report                                      ║
╚══════════════════════════════════════════════════════════════╝

URL:       https://example.com
Score:     88/100  [A]

┌──────────────────────────┬───────┬────────┬──────────┬────────┐
│ Category                 │ Score │ Passed │ Warnings │ Failed │
├──────────────────────────┼───────┼────────┼──────────┼────────┤
│ Core                     │ 97    │ 18     │ 1        │ 0      │
│ Performance              │ 85    │ 18     │ 3        │ 1      │
│ JavaScript Rendering     │ 100   │ 13     │ 0        │ 0      │
│ ...                      │       │        │          │        │
└──────────────────────────┴───────┴────────┴──────────┴────────┘

JSON Output

{
  "url": "https://example.com",
  "overallScore": 88,
  "categoryResults": [
    {
      "categoryId": "core",
      "score": 97,
      "passCount": 18,
      "warnCount": 1,
      "failCount": 0,
      "results": [...]
    }
  ],
  "timestamp": "2026-01-23T16:00:00.000Z",
  "crawledPages": 1
}

CI/CD Integration

GitHub Actions

name: SEO Audit

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install SEOmator
        run: npm install -g @seomator/seo-audit

      - name: Install Playwright browsers
        run: npx playwright install chromium

      - name: Run SEO Audit
        run: seomator audit https://your-staging-url.com --format json -o seo-report.json

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: seo-report
          path: seo-report.json

GitLab CI

seo-audit:
  image: node:20
  script:
    - npm install -g @seomator/seo-audit
    - npx playwright install chromium
    - seomator audit https://your-staging-url.com --format json -o seo-report.json
  artifacts:
    paths:
      - seo-report.json

Programmatic Usage

import { Auditor, createAuditor } from '@seomator/seo-audit';

const auditor = createAuditor({
  categories: ['core', 'security', 'perf'],
  measureCwv: true,
  onCategoryComplete: (categoryId, name, result) => {
    console.log(`${name}: ${result.score}/100`);
  }
});

const result = await auditor.audit('https://example.com');
console.log(`Overall Score: ${result.overallScore}`);

Claude Code Skill

Use SEOmator directly in Claude Code as an AI skill for automated SEO auditing.

Setup

npx skills add seo-skills/seo-audit-skill

Usage

"Run an SEO audit on https://example.com"
"Audit https://mysite.com and tell me what to fix first"
"Check SEO health of https://example.com with 20-page crawl"

Requirements

• Node.js 18+ (uses native fetch API)
• Playwright (for Core Web Vitals and JS rendering analysis)

After installing, run npx playwright install chromium to install the browser for CWV measurement.

For the desktop app, better-sqlite3 must be compiled for Electron's Node version:

npx electron-rebuild -f -w better-sqlite3

License

MIT