SEOmator SEO Audit Tool & Skill

SEOmator is a comprehensive SEO audit tool that scans any website against 373 rules across 20 categories — technical SEO, Core Web Vitals, structured data, accessibility, security headers, and AI/GEO search readiness — and returns a prioritized, actionable report. It ships as a command-line tool, an Electron desktop app, and a Claude Code skill, so you can run an SEO audit from a terminal, a visual dashboard, or directly inside an AI coding agent.

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

Contents

• Features
• Installation
• Desktop App
• Quick Start (CLI)
• Commands
• Categories & Rules
• Configuration
• Output Formats
• CI/CD Integration
• Programmatic Usage
• Claude Code Skill
• FAQ
• Requirements

Features

• 373 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
• Per-Asset Checks - Cache policy, text compression, image sizing, and redirect chains for every subresource loaded during render
• 5 Output Formats - Console, JSON, HTML, Markdown, and LLM-optimized XML
• Actionable Reports - Every rule ships a specific fix suggestion; unmeasurable checks report as "not measured" instead of fake passes
• 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 - Sitemap URLs cross-checked against status/canonical/robots.txt, canonical chains & loops, hreflang target validation and reciprocity, duplicate content & H1s, orphan & isolated pages, inbound link quality
• 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
npm run rebuild:electron   # 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.

Audits are stored in ~/.seomator/audits.db by default, which is what seomator report, seomator compare and the desktop app read. Set SEOMATOR_HOME to keep that data elsewhere, or [output] save = false in seomator.toml to opt a project out.

seomator serve

Run the local dashboard: every audit you have run, in your browser.

seomator serve                   # opens http://127.0.0.1:7360
seomator serve --port 0          # pick a free port
seomator serve --no-open         # do not open a browser

It reads the same ~/.seomator/audits.db the CLI writes, binds to loopback only, and makes no outbound requests. Every /api request needs the per-launch token, which is printed once and written to ~/.seomator/serve.json for agents:

TOKEN=$(jq -r .token ~/.seomator/serve.json)
curl -s -H "X-SEOmator-Token: $TOKEN" http://127.0.0.1:7360/api/audits | jq

Full reference: docs/WEB-DASHBOARD.md.

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 analyze [crawl-id]

Run rules on stored crawl data.

seomator analyze                           # Analyze latest crawl
seomator analyze --latest                  # Stored in your history by default
seomator analyze 2026-01-23-abc123         # Specific crawl

seomator report [query]

View and query past audits. Reads your history, falling back to the legacy JSON reports under .seomator/reports/.

seomator report --list                     # List stored audits
seomator report --project mysite           # Filter by project
seomator report 2026-09-02-a1b2c3          # Show one audit

seomator compare [domain]

Compare the latest audit of a site against a previous one, so you can see what a deploy changed. Requires at least two stored audits of the same domain.

seomator audit https://example.com           # run before the deploy
seomator audit https://example.com           # run after

seomator compare example.com                 # diff the two most recent runs
seomator compare example.com --trend         # score history for the domain
seomator compare example.com --against 2026-08-31-a1b2c3
seomator compare example.com --json          # machine-readable diff
seomator compare example.com --fail-on-regression   # exit 1 if worse (for CI)

Rules are diffed by ID, so a rule that broke and a different one that got fixed are reported separately rather than cancelling out in a count.

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

A page that cannot rank fails whatever its other checks score. In a single-page audit, the overall score is capped while a page-level condition holds: noindex or a robots.txt block (20), an empty page (30), fewer than 20 words of main content (49), no <title> (69). A crawl takes the noindex and robots.txt caps of its start page, so a site blocked everywhere fails. The report prints the cap under the score, and JSON keeps the uncapped average in scoreCap.uncappedScore.

A staging site is blocked on purpose: audit it with --staging. That waives the noindex and robots.txt caps, crawls past robots.txt, and lists what it waived as the launch checklist.

Categories & Rules (373 total)

Core (24 rules) - 11% weight

Performance (28 rules) - 10% weight

Links (27 rules) - 8% weight

Images (14 rules) - 8% weight

Security (26 rules) - 8% weight

Technical SEO (18 rules) - 7% weight

Crawlability (38 rules) - 5% weight

Structured Data (19 rules) - 5% weight

JavaScript Rendering (16 rules) - 5% weight

Accessibility (36 rules) - 7% weight

Content (27 rules) - 5% weight

Social (9 rules) - 3% weight

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

URL Structure (14 rules) - 3% weight

Redirects (11 rules) - 3% weight

Mobile (12 rules) - 2% weight

Internationalization (13 rules) - 2% weight

HTML Validation (11 rules) - 2% weight

AI/GEO Readiness (13 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"

FAQ

What is SEOmator?

SEOmator is an SEO audit tool that checks a website against 373 rules across 20 categories — covering technical SEO, Core Web Vitals, structured data, accessibility, security headers, content quality, and AI/GEO search readiness — and returns a scored, prioritized report of what to fix first. It's available as an open-source CLI, an Electron desktop app, and a Claude Code skill.

How is SEOmator different from Lighthouse or PageSpeed Insights?

Lighthouse and PageSpeed Insights focus on performance and Core Web Vitals for a single page. SEOmator includes CWV measurement but covers far more ground: crawlability, indexability, structured data validation, redirect chains, hreflang, E-E-A-T signals, and AI/GEO readiness (AI crawler access, llms.txt, semantic HTML) — across a full multi-page crawl, not just one URL.

Does SEOmator check AI search / GEO readiness?

Yes. The AI/GEO Readiness category checks whether AI crawlers like GPTBot and ClaudeBot are allowed in robots.txt, whether an /llms.txt file exists, whether heading structure and semantic HTML are AI-extractable, and whether JSON-LD schema matches the page's visible content.

Is SEOmator free to use?

The CLI (@seomator/seo-audit) is MIT-licensed and free to install and run locally or in CI/CD — see Installation. A hosted, no-install version is also available at seomator.com/free-seo-audit-tool.

Can I run SEOmator in CI/CD?

Yes. It returns exit code 0 for a passing score (≥70), 1 for a failing score, and 2 on error, plus JSON output for parsing. See the GitHub Actions and GitLab CI examples.

Can I use SEOmator with Claude or other AI agents?

Yes. The --format llm flag outputs token-efficient, injection-hardened XML designed for AI agents, and the Claude Code skill lets you run audits directly from a prompt like "Audit https://example.com and tell me what to fix first."

Requirements

• Node.js 20.3+ (required by better-sqlite3 and AbortSignal.any(); 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:

npm run rebuild:electron

License

MIT