seo-audit-skill

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.

Option	Alias	Description	Default
--format <type>	-f	Output format: console, json, html, markdown, llm	console
--output <path>	-o	Output file path	-
--categories <list>	-c	Comma-separated categories to audit	All
--json	-j	Output as JSON (deprecated, use --format json)	false
--crawl	-	Enable crawl mode for multiple pages	false
--max-pages <n>	-m	Maximum pages to crawl	10
--concurrency <n>	-	Concurrent requests	3
--timeout <ms>	-	Request timeout in milliseconds	30000
--no-cwv	-	Skip Core Web Vitals measurement	false
--mobile	-	Second render at a mobile viewport + mobile-first parity checks (single-page)	false
--simulate-interaction	-	Scroll and click the page so INP can be measured (reported as synthetic, unscored)	false
--staging	-	Audit a staging site: waive the noindex and robots.txt caps, and crawl past robots.txt	false
--verbose	-v	Show progress	false
--config <path>	-	Config file path	-
--no-save	-	Do not store this audit in your history	-
--json-report	-	Also write the legacy JSON report to .seomator/reports/	false

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

Code	Meaning
0	Audit passed (score >= 70)
1	Audit failed (score < 70)
2	Error occurred

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

Rule	Description
core-title-present	<title> tag exists
core-title-length	Title should be 30-60 characters
core-description-present	Meta description exists
core-description-length	Description should be 120-160 characters
core-canonical-present	Canonical URL exists
core-canonical-valid	Canonical URL is valid absolute URL
core-viewport-present	Viewport meta tag exists
core-favicon-present	Favicon link exists