### SEOmator CLI Quick Start Examples

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Demonstrates various ways to use the SEOmator CLI, including skipping Core Web Vitals, auditing specific categories, generating different output formats, and performing crawls.

```bash
# 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
```

--------------------------------

### Install and Run SEOmator from Source

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Clone the repository, install dependencies, build the project, and run the CLI tool directly or after linking it globally.

```bash
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
```

--------------------------------

### seomator init

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

Initializes the Seomator configuration by creating a `seomator.toml` file. This command can be run interactively to guide the user through setup or non-interactively using presets.

```APIDOC
## `seomator init` — Initialize Configuration

Creates a `seomator.toml` configuration file interactively or non-interactively using built-in presets.

### Usage

```bash
# Interactive setup
seomator init

# Use defaults non-interactively
seomator init -y

# Apply a preset
seomator init --preset blog       # Content/blog sites (emphasizes content, E-E-A-T)
seomator init --preset ecommerce  # E-commerce (emphasizes schema, performance)
seomator init --preset ci         # Minimal CI/CD (fast, essential rules only)
```

### Options

*   **-y, --yes** - Optional - Use default settings non-interactively.
*   **--preset** (string) - Optional - Apply a predefined configuration preset (e.g., `blog`, `ecommerce`, `ci`).
```

--------------------------------

### Check System Setup and Dependencies

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Run a diagnostic check on the system setup and dependencies required by Seomator. Supports verbose output for detailed diagnostics.

```bash
seomator self doctor -v          # Verbose diagnostics
```

--------------------------------

### Install and Run SEOmator CLI

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

Install the SEOmator CLI globally using npm. Verify the installation and system requirements with `seomator self doctor`. Run a basic audit on a given URL.

```bash
npm install -g @seomator/seo-audit

seomator self doctor

seomator audit https://example.com
```

--------------------------------

### Install and Run SEOmator CLI

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Install the SEOmator CLI tool globally using npm and run a basic audit on a given URL.

```bash
npm install -g @seomator/seo-audit

seomator audit https://example.com
```

--------------------------------

### Create Seomator Configuration File

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Initialize a new `seomator.toml` configuration file. Supports interactive setup, default values, and predefined presets.

```bash
seomator init                    # Interactive setup
```

```bash
seomator init -y                 # Use defaults
```

```bash
seomator init --preset blog      # Blog preset
```

```bash
seomator init --preset ecommerce # E-commerce preset
```

```bash
seomator init --preset ci        # Minimal CI config
```

--------------------------------

### Example: Fresh Audit After Changes

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/SKILL.md

Re-audit a website, ensuring cached results are ignored to get the most up-to-date SEO analysis.

```bash
# User asks: "Re-audit the site, ignore cached results"
seomator audit https://example.com --refresh --format llm --no-cwv
```

--------------------------------

### Electron-Builder Configuration Example

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/ELECTRON-APP.md

This table outlines key settings for electron-builder configuration in `electron-builder.yml`.

```yaml
appId: com.seomator.desktop
productName: SEOmator
buildResources: electron/resources/
output: release/
asar: true (with .node files unpacked)
```

--------------------------------

### Install SEOmator CLI

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/quickstart.md

Installs the SEOmator command-line interface globally. Requires Node.js 18+.

```bash
npm install -g @seomator/seo-audit
```

--------------------------------

### Install and Run SEOmator CLI

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/README.md

Install the SEOmator CLI globally using npm and run a basic audit on a given URL. For multi-page crawls, use the --crawl and -m options.

```bash
npm install -g @seomator/seo-audit
```

```bash
seomator audit https://example.com
```

```bash
seomator audit https://example.com --crawl -m 20
```

--------------------------------

### Verify SEOmator Skill Installation

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/ai-agent-integration.md

After installation, verify that the `seo-audit` skill is available in your AI agent's skill list.

```bash
npx skills list
```

--------------------------------

### Initialize SEOmator Configuration

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/quickstart.md

Use `seomator init` to create a configuration file. Interactive setup is default, but you can use `-y` for defaults or `--preset` to apply predefined configurations like 'blog'.

```bash
seomator init
```

```bash
seomator init -y
```

```bash
seomator init --preset blog
```

--------------------------------

### Initialize Seomator Configuration

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/SKILL.md

Run `seomator init` to create a `seomator.toml` configuration file. Use flags for non-interactive setup or to apply presets like 'blog', 'ecommerce', or 'ci'.

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

--------------------------------

### CLI Usage Examples

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

Examples of using the SEOmator CLI for SEO audits, including piping output to an LLM and integrating with GitHub Actions.

```APIDOC
## Pipe to Claude with a specific task
seomator audit https://example.com --crawl -m 20 --format llm --no-cwv \
  | claude "Create a prioritized fix plan grouped by category"
```

```APIDOC
## GitHub Actions CI/CD integration
# (exits 1 if overall score < 70, 0 if passing)
seomator audit https://staging.example.com --format json -o seo-report.json
```

```APIDOC
## GitHub Actions workflow example
```yaml
name: SEO Audit
on:
  push:
    branches: [main]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @seomator/seo-audit
      - run: npx playwright install chromium
      - run: seomator audit https://your-staging-url.com --format json -o seo-report.json
      - uses: actions/upload-artifact@v4
        with:
          name: seo-report
          path: seo-report.json
```
```

--------------------------------

### Run SEOmator Desktop App from Source

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Clone the repository, install dependencies, rebuild native modules for Electron, and launch the development version of the desktop app.

```bash
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
```

--------------------------------

### Project Database Usage Example

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/STORAGE-ARCHITECTURE.md

Demonstrates opening a project database, creating projects and crawls, inserting pages with automatic compression, and completing a crawl.

```typescript
import { ProjectDatabase } from '../storage/project-db/index.js';

// Open/create database for a domain
const db = new ProjectDatabase('example.com');

// Or from a full URL (domain is extracted)
const db2 = new ProjectDatabase('https://www.example.com/path');

// Get or create project
const project = db.getOrCreateProject('My Website');

// Create a crawl
const crawl = db.createCrawl({
  crawlId: '2024-01-23-abc123',
  startUrl: 'https://example.com',
  config: { /* ... */ },
});

// Insert pages with automatic HTML compression
db.insertPage(crawl.id, {
  url: 'https://example.com/page',
  statusCode: 200,
  depth: 1,
  html: '<html>...</html>',  // Auto-compressed if > 10KB
  headers: { 'content-type': 'text/html' },
  loadTimeMs: 250,
});

// Complete the crawl
db.completeCrawl(crawl.crawlId, {
  totalPages: 10,
  duration: 5000,
  errorCount: 0,
});

// Close when done
db.close();
```

--------------------------------

### Verify SEO Audit Skill Installation

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/ai-agent-integration.md

Check if the SEO audit skill is installed correctly by listing installed skills and filtering for 'seo-audit'.

```bash
npx skills list | grep seo-audit
```

--------------------------------

### Example: Quick Audit with LLM Output

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/SKILL.md

Perform a quick SEO audit of a website and receive output optimized for AI agents.

```bash
# User asks: "Check example.com for SEO issues"
seomator audit https://example.com --format llm --no-cwv
```

--------------------------------

### Example SEOmator Configuration File

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/quickstart.md

A sample `seomator.toml` file demonstrating project settings, crawler behavior, rule enablings/disablings, and output format.

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

[crawler]
max_pages = 100
concurrency = 3
timeout_ms = 30000
exclude = ["/admin/**", "/api/**"]

[rules]
enable = ["*"]
disable = ["perf-inp"]

[output]
format = "console"
```

--------------------------------

### GitHub Actions Workflow for SEOmator Audit

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Automate SEOmator SEO audits within a GitHub Actions workflow. This example demonstrates installation, running the audit, and uploading the report artifact.

```yaml
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

```

--------------------------------

### Programmatic SEO Audit with Custom Reporting (TypeScript)

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

Full TypeScript example demonstrating the programmatic API for running an SEO audit with custom logging for category start and completion. Includes error handling and custom grading based on the overall score.

```typescript
import { createAuditor, type AuditResult, type CategoryResult } from '@seomator/seo-audit';

async function runSeoAudit(url: string): Promise<void> {
  const auditor = createAuditor({
    categories: [],          // empty = all 20 categories
    timeout: 30000,
    measureCwv: true,        // requires Chrome/Chromium

    onCategoryStart: (id, name) => {
      process.stdout.write(`  Auditing ${name.padEnd(25)}`);
    },
    onCategoryComplete: (id, name, result) => {
      const icon = result.score >= 70 ? '✓' : '✗';
      console.log(`${icon} ${result.score}/100`);
    },
  });

  let result: AuditResult;
  try {
    result = await auditor.auditWithCrawl(url, 10, 3);
  } catch (err) {
    console.error('Audit error:', err instanceof Error ? err.message : err);
    process.exit(2);
  }

  // Grade mapping
  const grade = result.overallScore >= 90 ? 'A'
    : result.overallScore >= 80 ? 'B'
    : result.overallScore >= 70 ? 'C'
    : result.overallScore >= 50 ? 'D' : 'F';

  console.log(`
Overall: ${result.overallScore}/100 (${grade}) — ${result.crawledPages} pages
`);

  // Print failures only
  const failures = result.categoryResults
    .flatMap((cat: CategoryResult) => cat.results.map(r => ({ ...r, catId: cat.categoryId })))
    .filter(r => r.status === 'fail')
    .sort((a, b) => a.catId.localeCompare(b.catId));

  if (failures.length > 0) {
    console.log(`Failures (${failures.length}):`);
    failures.forEach(f => console.log(`  [${f.catId}] ${f.ruleId}: ${f.message}`));
  }

  process.exit(result.overallScore >= 70 ? 0 : 1);
}

runSeoAudit('https://example.com');

```

--------------------------------

### Example Seomator Configuration File

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

A sample `seomator.toml` file demonstrating project settings, crawler configurations, rule management, external link settings, and output preferences.

```toml
[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
user_agent = ""
include = []
exclude = ["/admin/**", "/api/**", "/wp-json/**"]
drop_query_prefixes = ["utm_", "gclid", "fbclid", "mc_", "_ga"]
allow_query_params = []
max_prefix_budget = 0.25   # prevent over-crawling a single path prefix

[rules]
enable = ["*"]             # enable all rules (supports wildcards)
disable = ["perf-inp"]     # disable specific rules

[external_links]
enabled = true
cache_ttl_days = 7
timeout_ms = 10000
concurrency = 5

[output]
format = "llm"             # default output format
path = ""
```

--------------------------------

### Install SEOmator CLI and Playwright Dependencies

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/skill/README.md

Install the SEOmator CLI globally and download the necessary Playwright browsers. This is required before running audits.

```bash
npm install -g @seomator/seo-audit
```

```bash
npx playwright install chromium
```

--------------------------------

### Example: Generate Shareable Report

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/SKILL.md

Create a shareable HTML report of an SEO audit, including a crawl of up to 20 pages.

```bash
# User asks: "Create an HTML report I can share"
seomator audit https://example.com --crawl -m 20 --format html -o seo-report.html
```

--------------------------------

### Programmatic API - TypeScript Example

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

A full TypeScript example demonstrating the programmatic API for running SEO audits, including custom reporting and error handling.

```APIDOC
## Programmatic API — Full TypeScript Example

Complete end-to-end example using the programmatic API with custom reporting.

```typescript
import { createAuditor, type AuditResult, type CategoryResult } from '@seomator/seo-audit';

async function runSeoAudit(url: string): Promise<void> {
  const auditor = createAuditor({
    categories: [],          // empty = all 20 categories
    timeout: 30000,
    measureCwv: true,        // requires Chrome/Chromium

    onCategoryStart: (id, name) => {
      process.stdout.write(`  Auditing ${name.padEnd(25)}`);
    },
    onCategoryComplete: (id, name, result) => {
      const icon = result.score >= 70 ? '✓' : '✗';
      console.log(`${icon} ${result.score}/100`);
    },
  });

  let result: AuditResult;
  try {
    result = await auditor.auditWithCrawl(url, 10, 3);
  } catch (err) {
    console.error('Audit error:', err instanceof Error ? err.message : err);
    process.exit(2);
  }

  // Grade mapping
  const grade = result.overallScore >= 90 ? 'A'
    : result.overallScore >= 80 ? 'B'
    : result.overallScore >= 70 ? 'C'
    : result.overallScore >= 50 ? 'D' : 'F';

  console.log(`\nOverall: ${result.overallScore}/100 (${grade}) — ${result.crawledPages} pages\n`);

  // Print failures only
  const failures = result.categoryResults
    .flatMap((cat: CategoryResult) => cat.results.map(r => ({ ...r, catId: cat.categoryId })))
    .filter(r => r.status === 'fail')
    .sort((a, b) => a.catId.localeCompare(b.catId));

  if (failures.length > 0) {
    console.log(`Failures (${failures.length}):`);
    failures.forEach(f => console.log(`  [${f.catId}] ${f.ruleId}: ${f.message}`));
  }

  process.exit(result.overallScore >= 70 ? 0 : 1);
}

runSeoAudit('https://example.com');
```
```

--------------------------------

### Check SEOmator CLI Installation

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/ai-agent-integration.md

Verify that the SEOmator CLI tool is installed by checking its version. This is a prerequisite for running audits.

```bash
seomator --version
```

--------------------------------

### Development Environment Configuration

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/configuration.md

Example TOML configuration for a development environment. Includes a lower `max_pages` limit and a longer `timeout_ms`.

```toml
[project]
name = "my-site-dev"

[crawler]
max_pages = 10
timeout_ms = 60000    # Longer timeout for slow dev server

[rules]
disable = ["security-*"]  # Skip security rules in dev
```

--------------------------------

### Verify SEOmator Installation

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/quickstart.md

Runs a self-check to ensure SEOmator is set up correctly. This command verifies dependencies and configurations.

```bash
seomator self doctor
```

--------------------------------

### Production Environment Configuration

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/configuration.md

Example TOML configuration for a production environment. Sets a higher `max_pages` limit and enables `respect_robots`.

```toml
[project]
name = "my-site"

[crawler]
max_pages = 500
respect_robots = true

[external_links]
enabled = true
cache_ttl_days = 1    # More frequent link checks
```

--------------------------------

### CI/CD Environment Configuration

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/configuration.md

Example TOML configuration for a CI/CD environment. Sets `max_pages`, `concurrency`, and specifies `json` output format.

```toml
[project]
name = "my-site-ci"

[crawler]
max_pages = 50
concurrency = 5

[output]
format = "json"

[rules]
disable = ["perf-inp", "perf-cls"]  # Skip flaky CWV rules in CI
```

--------------------------------

### TypeScript Database Type Examples

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/STORAGE-ARCHITECTURE.md

Provides examples of TypeScript interfaces for raw database records (Db*) and hydrated application-ready records (Hydrated*), illustrating naming conventions and data type transformations.

```typescript
// Raw database record
interface DbPage {
  id: number;
  crawl_id: number;
  url: string;
  html_compressed: number;  // 0 or 1
  // ...
}

// Hydrated for application use
interface HydratedPage {
  id: number;
  crawlId: number;         // camelCase
  url: string;
  htmlCompressed: boolean; // boolean, not 0/1
  crawledAt: Date;         // Date, not string
  // ...
}
```

--------------------------------

### Full TOML Configuration Example

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/configuration.md

This TOML file demonstrates a comprehensive configuration for SEOmator, covering project details, crawler settings, URL filtering, rule management, external link checking, and output formatting.

```toml
[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
user_agent = ""                 # Empty = random browser UA per crawl

# URL filtering (glob patterns)
include = []                    # Empty = crawl all
exclude = ["/admin/**", "/api/**", "/wp-json/**"]

# Query param handling
drop_query_prefixes = ["utm_", "gclid", "fbclid", "ref"]
allow_query_params = []         # Empty = keep all except dropped

# Crawl distribution
max_prefix_budget = 0.25        # Prevent over-crawling single paths (0-1)

[rules]
enable = ["*"]                  # Enable all rules by default
disable = ["perf-inp"]          # Disable specific rules (supports wildcards)

[external_links]
enabled = true
cache_ttl_days = 7
timeout_ms = 10000
concurrency = 5

[output]
format = "console"              # console, json, html, markdown, llm
path = ""                       # Output file path (optional)
```

--------------------------------

### Electron Development Workflow Command

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/ELECTRON-APP.md

Use this command to start the development mode, enabling Vite HMR and Electron hot reloading.

```bash
# Start dev mode (Vite HMR + Electron hot reload)
npm run electron:dev

# In dev mode:
# - Renderer loads from Vite dev server (localhost:5173)
# - Main process restarts on file changes
# - DevTools open automatically
```

--------------------------------

### Configure GitLab CI for SEO Audits

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Set up a GitLab CI job to automate SEO audits. This configuration installs the SEO audit tool, installs Playwright dependencies, runs an audit on a specified URL, and saves the report as a JSON artifact.

```yaml
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
```

--------------------------------

### Get and Set Configuration Values

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/configuration.md

Use the `seomator config` command to retrieve or modify individual configuration settings. Use the `--global` flag to modify the global configuration.

```bash
seomator config crawler.max_pages         # Get value
```

```bash
seomator config crawler.max_pages 50      # Set value
```

```bash
seomator config --global                  # Modify global config
```

--------------------------------

### Integrate SEOmator with AI Agents

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

Instructions for integrating SEOmator into AI agent workflows, either by installing it as a skill for platforms like Claude Code/Cursor or by piping its LLM output to an LLM for processing.

```bash
# Install as a Claude Code / Cursor skill
npx skills add seo-skills/seo-audit-skill

# Use in Claude Code with slash command
# /seo-audit https://example.com

# Pipe to Claude CLI for instant analysis
seomator audit https://example.com --format llm --no-cwv | claude "Fix all critical issues"
```

--------------------------------

### Wildcard Rule Examples

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/configuration.md

Configure rule enablement and disablement using wildcards. This allows for broad application of settings across rule categories or specific rule names.

```toml
[rules]
enable = ["*"]                    # Enable all rules
disable = [
  "perf-*",                       # Disable all performance rules
  "a11y-color-contrast",          # Disable specific rule
  "content-word-count",
]
```

--------------------------------

### Example Prompts for SEOmator Audit Skill

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/skill/README.md

Use these prompts to initiate an SEO audit with the SEOmator skill. Specify the URL and optionally the crawl depth.

```text
"Run an SEO audit on https://example.com"
```

```text
"Audit https://mysite.com and tell me what to fix first"
```

```text
"Check the SEO health of https://example.com with a 20-page crawl"
```

```text
"What SEO issues does https://example.com have?"
```

--------------------------------

### Run Electron app in development mode

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/claude.md

Start the Electron desktop app in development mode, enabling Vite HMR and Electron hot reloading for a faster development cycle.

```bash
npm run electron:dev   # Dev mode with Vite HMR + Electron hot reload
```

--------------------------------

### Programmatically Load Seomator Configuration

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

The `loadConfig` function from `@seomator/seo-audit` programmatically loads and merges Seomator's configuration from various sources. It accepts a starting directory and optional CLI overrides, returning the merged configuration and the path to the resolved TOML file.

```typescript
import { loadConfig, mergeConfigs } from '@seomator/seo-audit';
// Note: config functions are exported from the internal config module
// For direct use: import { loadConfig } from './src/config/index.js'

const { config, configPath } = loadConfig(process.cwd(), {
  crawler: {
    max_pages: 25,
    concurrency: 5,
  },
});

console.log(configPath);                  // '/home/user/project/seomator.toml' or null
console.log(config.crawler.max_pages);    // 25 (CLI override applied)
console.log(config.rules.enable);         // ['*']
console.log(config.output.format);        // 'console'

// SeomatorConfig shape:
// {
//   project:        { name, domains }
//   crawler:        { max_pages, concurrency, timeout_ms, delay_ms, respect_robots,
//                     include, exclude, drop_query_prefixes, allow_query_params,
//                     user_agent, max_prefix_budget, breadth_first, follow_redirects,
//                     per_host_concurrency, per_host_delay_ms }
//   rules:          { enable, disable }
//   external_links: { enabled, cache_ttl_days, timeout_ms, concurrency }
//   output:         { format, path }
//   rule_options:   Record<string, Record<string, unknown>>
// }
```

--------------------------------

### Prompt AI Agent with Skill

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/introduction.md

Instruct your AI agent to use the installed SEOmator skill for auditing and fixing website issues. This is an example prompt.

```bash
Use the seo-audit skill to audit this site and fix all issues
```

--------------------------------

### Initialize SEOmator Configuration

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/README.md

Create a default configuration file for SEOmator using the init command.

```bash
seomator init
```

--------------------------------

### Initialize SEOmator with Presets

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/configuration.md

Use presets to quickly configure SEOmator for specific use cases like content sites, e-commerce, or CI/CD environments.

```bash
seomator init --preset blog       # Content sites
seomator init --preset ecommerce  # E-commerce sites
seomator init --preset ci         # Minimal CI/CD config
```

--------------------------------

### View CLI Help

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/SKILL.md

Access help documentation for the seomator CLI and specific commands to understand available options and usage.

```bash
seomator --help
```

```bash
seomator <command> --help
```

--------------------------------

### LLM Format Output Example

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

An example of the LLM (Large Language Model) output format, which is an XML-based representation of the SEO audit results. This format is compact and suitable for AI agents.

```xml
<seo-audit url="https://example.com" score="88" grade="B" pages="1" date="2026-01-23">
  <summary passed="214" warnings="18" failures="19"/>
  <categories>
    <cat id="core" score="97" p="18" w="1" f="0"/>
    <cat id="perf" score="85" p="18" w="3" f="1"/>
  </categories>
  <issues>
    <issue severity="critical" rule="security-csp" cat="security">
      <msg>Content-Security-Policy header missing</msg>
      <fix>Add a Content-Security-Policy header to your server response</fix>
    </issue>
  </issues>
  <passed>core-title-present, core-title-length, core-canonical-present, ...</passed>
</seo-audit>
```

--------------------------------

### Build Electron app for production

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/claude.md

Create a production build of the Electron desktop app, including the main process, preload scripts, and renderer.

```bash
npm run electron:build # Production build (main + preload + renderer)
```

--------------------------------

### Example Prompts for Claude Code SEO Audit Skill

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Illustrative prompts for interacting with the SEO Audit Skill in Claude Code. These examples show how to request audits for specific URLs and prioritize fixes.

```text
"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"
```

--------------------------------

### Electron-Vite Build Process Overview

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/ELECTRON-APP.md

This diagram illustrates the parallel Vite builds managed by electron-vite for the main, preload, and renderer processes.

```text
electron-vite build
  ├── main/index.ts      → dist-electron/main/index.js        (Node.js, ESM)
  ├── preload/index.ts   → dist-electron/preload/index.mjs    (Node.js, ESM)
  └── renderer/index.html → dist-electron/renderer/            (Browser, React+CSS)
```

--------------------------------

### Build and Package SEOmator Desktop App

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/README.md

Commands to create a production build or a packaged distributable version of the SEOmator desktop application.

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

--------------------------------

### Example: Focus on Specific Areas

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/SKILL.md

Audit only specific SEO categories, such as JavaScript rendering and redirects, for a targeted analysis.

```bash
# User asks: "Just check my JavaScript rendering and redirects"
seomator audit https://example.com -c js,redirect --format llm
```

--------------------------------

### Initialize and Use the Low-Level Crawler

Source: https://context7.com/seo-skills/seo-audit-skill/llms.txt

Demonstrates how to instantiate and use the internal queue-based concurrent crawler to collect raw page data with progress callbacks. Configure crawler options like maxPages, concurrency, timeout, and URL filtering.

```typescript
import { Crawler, type CrawledPage, type CrawlProgress } from '@seomator/seo-audit';
// Internal import: import { Crawler } from './src/crawler/index.js'

const crawler = new Crawler({
  maxPages: 50,
  concurrency: 3,
  timeout: 30000,
  onProgress: (progress: CrawlProgress) => {
    process.stdout.write(
      `\rCrawled: ${progress.crawled}/${progress.total} | Discovered: ${progress.discovered} | ${progress.currentUrl.slice(0, 60)}`
    );
  },
  urlFilter: {
    include: ['/blog/**'],
    exclude: ['/admin/**', '/api/**'],
    dropQueryPrefixes: ['utm_', 'gclid'],
    allowQueryParams: ['page'],
  },
});

const pages: CrawledPage[] = await crawler.crawl('https://example.com', 50, 3);
console.log(`\nCrawled ${pages.length} pages`);

for (const page of pages) {
  if (page.error) {
    console.warn(`  ERROR ${page.url}: ${page.error}`);
    continue;
  }
  console.log(`  ${page.context.statusCode} ${page.url} (${page.context.responseTime}ms)`);
  // page.context: AuditContext with .html, .$, .headers, .links, .images, .cwv etc.
}
```

--------------------------------

### Package Electron app for distribution

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/claude.md

Build and package the Electron desktop app into a distributable format.

```bash
npm run electron:pack  # Build + package into distributable
```

--------------------------------

### Querying Audit Results

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/STORAGE-ARCHITECTURE.md

Provides examples of querying audit results by status, rule, page, severity, and retrieving score trends for a domain.

```typescript
// Get all failed results
const failures = auditsDb.getResultsByStatus(audit.id, 'fail');

// Get results for a specific rule
const titleResults = auditsDb.getResultsByRule(audit.id, 'title-present');

// Get results for a specific page
const pageResults = auditsDb.getResultsByPage(audit.id, 'https://example.com/contact');

// Get issues by severity
const criticalIssues = auditsDb.getIssuesBySeverity(audit.id, 'critical');

// Get score trend for a domain
const trend = auditsDb.getScoreTrend('example.com', 10);
```

--------------------------------

### SEOmator Configuration File Structure

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/technical-architecture.md

Illustrates the directory structure and files related to the SEOmator configuration system.

```tree
src/config/
├── schema.ts      # TypeScript type definitions
├── defaults.ts    # Default values & presets
├── loader.ts      # Config file discovery & loading
├── writer.ts      # Config file generation (init)
└── validator.ts   # Config validation
```

--------------------------------

### Generate Custom Audit Report

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/technical-architecture.md

This TypeScript example shows how to create a new reporter by defining a function that transforms the audit report into a custom format.

```typescript
// src/reporters/my-reporter.ts
import type { AuditReport } from '../types.js';

export function generateMyReport(report: AuditReport): string {
  // Transform report to your format
  return myFormat;
}
```

--------------------------------

### Example: Deep Crawl for Large Site

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/SKILL.md

Conduct a thorough SEO audit of a large website, crawling up to 100 pages and optimizing output for AI.

```bash
# User asks: "Do a thorough audit with up to 100 pages"
seomator audit https://example.com --crawl -m 100 --format llm --no-cwv
```

--------------------------------

### CLI Migration Commands

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/STORAGE-ARCHITECTURE.md

Shows the command-line interface commands for migrating existing JSON crawl and report data to the database, including previewing, running, and rolling back.

```bash
# Preview migration
seomator db migrate --dry-run

# Run migration (creates backups)
seomator db migrate

# Rollback if needed
seomator db restore
```

--------------------------------

### Other Seomator Commands

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/SKILL.md

Manage configuration, check system health, list reports, or view database statistics using these utility commands.

```bash
seomator init              # Create config file
seomator self doctor       # Check system setup
seomator config --list     # Show all config values
seomator report --list     # List past reports
seomator db stats          # Show database statistics
```

--------------------------------

### Reinstall SEO Audit Skill

Source: https://github.com/seo-skills/seo-audit-skill/blob/main/docs/ai-agent-integration.md

Force reinstall the SEO audit skill if it is missing or corrupted. Use the `--force` flag to ensure a clean installation.

```bash
npx skills add seo-skills/seo-audit-skill --force
```