Running audits

Learn how to run comprehensive website audits with squirrel, from quick health checks to deep analysis.

All audit results are stored in a local database at ~/.squirrel/projects/<project-name>, allowing you to generate multiple report formats from a single crawl.

Basic audit command

The simplest way to audit a website:

squirrel audit https://example.com

This command:

Crawls up to 100 pages (default surface mode)
Analyzes against 230+ rules
Displays console output with colored formatting
Saves results to the local database

Always include the protocol (https:// or http://) in the URL.

Quick start examples

squirrel audit https://example.com

Coverage modes explained

Choose the scan depth that matches your needs:

Quick
Surface
Full

Quick mode

25 pages - Fastest scan for rapid health checks

squirrel audit https://example.com --coverage quick
# or use the alias
squirrel audit https://example.com -C quick

How it works

Crawls seed URLs only (homepage, sitemap entries)
No link discovery - doesn’t follow internal links
Focuses on primary pages and templates

Best for

CI/CD pipelines

Fast checks on every deployment

Health monitoring

Daily status checks

Rapid feedback

Quick validation during development

Quick mode may miss issues on pages not in sitemaps or seed URLs.

Surface mode (Default)

100 pages - Smart sampling of unique templates

squirrel audit https://example.com --coverage surface
# or simply
squirrel audit https://example.com

How it works

Detects URL patterns like /blog/{slug} or /products/{id}
Crawls one sample per pattern
Discovers links and explores site structure
Balances coverage with speed

Pattern detection example

For a blog with 500 posts at /blog/{slug}:

Surface mode: Crawls 1 sample post
Full mode: Would crawl all 500 posts

This makes surface mode ideal for sites with many similar pages.

Best for

General audits

Most common use case

Template coverage

Validates all page types

Regular monitoring

Weekly or monthly checks

Full mode

500 pages (default) - Comprehensive deep dive

squirrel audit https://example.com --coverage full
# or use the alias
squirrel audit https://example.com -C full

How it works

Crawls everything up to the page limit
Follows all internal links
Discovers deep pages and edge cases
Most thorough analysis

Override page limit

# Increase to 1000 pages
squirrel audit https://example.com -C full --max-pages 1000

# Maximum allowed is 5000
squirrel audit https://example.com -C full -m 5000

Best for

Pre-launch audits

Complete validation before going live

Deep analysis

Thorough investigation of issues

Certification

Meeting strict quality standards

Full audits take longer (several minutes for large sites) but provide the most comprehensive results.

Coverage mode comparison

Mode	Pages	Link Discovery	Use Case	Speed
`quick`	25	No	CI checks, monitoring	⚡⚡⚡ Fastest
`surface`	100	Yes (sampled)	General audits	⚡⚡ Fast
`full`	500	Yes (complete)	Deep analysis	⚡ Thorough

Format options

Choose the output format that fits your workflow:

LLM
Console
JSON
HTML
Markdown

LLM format (Recommended for AI)

Compact XML/text hybrid optimized for AI agents:

squirrel audit https://example.com --format llm

Features

40% more compact than verbose XML
Token-efficient structure
Includes summary, issues, broken links, and recommendations
Organized by category for easy parsing

Output structure

<audit>
  <summary>
    <score>78</score>
    <grade>C</grade>
    ...
  </summary>
  <issues>
    <category name="Core SEO">
      <issue rule="missing-meta-description" severity="warning" ...>
    </category>
  </issues>
  <broken-links>...</broken-links>
  <recommendations>...</recommendations>
</audit>

Console format (Default)

Human-readable terminal output:

squirrel audit https://example.com
# equivalent to
squirrel audit https://example.com --format console

Features

Colored output for readability
Progress indicators during crawl
Summary statistics
Top issues highlighted

This is the default format when no --format is specified.

JSON format

Structured data for programmatic access:

squirrel audit https://example.com --format json -o report.json

Features

Complete audit data
Easy to parse and integrate
Supports filtering and querying

Example output

{
  "audit_id": "a1b2c3d4",
  "timestamp": "2024-10-11T10:30:00Z",
  "url": "https://example.com",
  "score": 78,
  "grade": "C",
  "issues": [...],
  "categories": {...}
}

HTML format

Interactive web report:

squirrel audit https://example.com --format html -o report.html

Features

Sortable tables
Filtering by category or severity
Visual charts and graphs
Share with stakeholders

Open the generated file in a browser to view the interactive report.

Markdown format

Documentation-friendly output:

squirrel audit https://example.com --format markdown -o report.md

Features

Include in wikis or documentation
Version control friendly
Easy to read and edit
Supports tables and lists

Format comparison

Format	Best For	Interactive	File Size
`llm`	AI agents, automation	No	Small
`console`	Terminal viewing	No	N/A
`json`	Integration, APIs	No	Medium
`html`	Stakeholders, sharing	Yes	Large
`markdown`	Documentation	No	Small

Advanced options

Refresh: Force fresh crawl

Ignore cached results and fetch all pages fresh:

squirrel audit https://example.com --refresh
# or use the alias
squirrel audit https://example.com -r

When to use

After making significant changes to the site
When you suspect cached data is stale
For comparing before/after deployment

Fresh crawls take longer and may impact the target website’s server load.

Resume: Continue interrupted crawl

Resume a crawl that was stopped or interrupted:

squirrel audit https://example.com --resume

When to use

Network interruption during crawl
Timeout on large sites
Manually stopped audit

The crawler tracks progress in the database, allowing it to pick up where it left off.

Max pages: Override page limit

Crawl more or fewer pages than the default:

# Audit up to 200 pages
squirrel audit https://example.com --max-pages 200

# Using alias
squirrel audit https://example.com -m 200

# Maximum is 5000
squirrel audit https://example.com -m 5000

Page limit by coverage

Default limits can be overridden:

Quick: 25 pages (can increase to 100)
Surface: 100 pages (can increase to 500)
Full: 500 pages (can increase to 5000)

Verbose: Detailed logging

Display detailed progress and debugging information:

squirrel audit https://example.com --verbose
# or use the alias
squirrel audit https://example.com -v

Output includes

URLs being crawled
Rule execution details
Timing information
Cache hit/miss status

Use verbose mode when diagnosing issues or monitoring large crawls.

Debug: Maximum logging

Enable debug-level logging for troubleshooting:

squirrel audit https://example.com --debug

Outputs extensive internal information including HTTP requests, rule evaluations, and database operations.

Trace: Performance profiling

Enable performance tracing:

squirrel audit https://example.com --trace

Tracks timing and resource usage for performance optimization.

Project name: Override config

Use a different project name for this audit:

squirrel audit https://example.com --project-name temp-audit
# or use alias
squirrel audit https://example.com -n temp-audit

This stores the audit in ~/.squirrel/projects/temp-audit/ instead of the configured project.

Combining options

Advanced options can be combined:

# Full fresh audit with verbose output
squirrel audit https://example.com \
  --coverage full \
  --max-pages 1000 \
  --refresh \
  --format llm \
  --verbose

Two-step workflow

For maximum efficiency, separate crawling from report generation:

Run the audit

Execute the audit once and save to database:

squirrel audit https://example.com --coverage full

The output will include an audit ID (e.g., a1b2c3d4).

Generate multiple reports

Export the same audit in different formats without re-crawling:

# LLM format for AI analysis
squirrel report a1b2c3d4 --format llm

# JSON for integration
squirrel report a1b2c3d4 --format json -o report.json

# HTML for stakeholders
squirrel report a1b2c3d4 --format html -o report.html

# Markdown for documentation
squirrel report a1b2c3d4 --format markdown -o report.md

This approach saves time and bandwidth - crawl once, export many times.

Finding audit IDs

List recent audits to find IDs:

squirrel report --list
# or use alias
squirrel report -l

Output:

Recent audits:
  a1b2c3d4 - example.com - 2024-10-11 10:30:00 - Score: 78
  e5f6g7h8 - example.com - 2024-10-10 15:45:00 - Score: 72

Filtering reports

Generate focused reports by filtering results:

By severity
By category
Combine filters

Show only errors or warnings:

# Only errors
squirrel report a1b2c3d4 --severity error --format llm

# Errors and warnings
squirrel report a1b2c3d4 --severity warning --format llm

# Everything (default)
squirrel report a1b2c3d4 --severity all --format llm

Focus on specific audit categories:

# Only Core SEO issues
squirrel report a1b2c3d4 --category "Core SEO" --format llm

# Multiple categories (comma-separated)
squirrel report a1b2c3d4 \
  --category "Core SEO,Technical SEO,Performance" \
  --format llm

Use multiple filters together:

# SEO errors only
squirrel report a1b2c3d4 \
  --category "Core SEO,Technical SEO" \
  --severity error \
  --format llm

Regression detection

Compare audits to detect regressions:

Compare by ID
Compare by domain

Compare current state against a baseline audit:

squirrel report --diff a1b2c3d4 --format llm

Where a1b2c3d4 is the baseline audit ID.

Compare latest audit against the last audit of a domain:

squirrel report --regression-since example.com --format llm

Diff mode supports console, text, json, llm, and markdown formats. HTML and XML are not supported for diffs.

Diff output

The diff report highlights:

New issues that weren’t present in the baseline
Fixed issues that were resolved
Score changes (improved or degraded)
Category changes

Common workflows

Quick health check

Fast validation during development:

squirrel audit https://localhost:3000 \
  --coverage quick \
  --format console

CI/CD integration

Automated checks on deployment:

# Run audit
squirrel audit https://staging.example.com \
  --coverage quick \
  --format json \
  -o audit-results.json

# Parse results in CI script
SCORE=$(jq '.score' audit-results.json)
if [ $SCORE -lt 85 ]; then
  echo "Audit failed: score below threshold"
  exit 1
fi

Pre-launch audit

Comprehensive validation before going live:

# Full audit with all details
squirrel audit https://staging.example.com \
  --coverage full \
  --max-pages 1000 \
  --refresh \
  --format llm

# Generate stakeholder report
squirrel report <audit-id> --format html -o launch-audit.html

Monitoring changes

Track site health over time:

# Weekly audit
squirrel audit https://example.com \
  --coverage surface \
  --format llm \
  -o "audit-$(date +%Y-%m-%d).txt"

# Compare with last week
squirrel report --diff <last-week-audit-id> --format markdown

Best practices

Start with surface

Begin with surface mode to get fast feedback on site structure and templates

Use LLM format for automation

The LLM format is optimized for AI agents and automated workflows

Save audit IDs

Keep track of audit IDs for historical comparisons and regression detection

Refresh before comparisons

Use --refresh when comparing before/after changes to ensure fresh data

Next steps

Audit categories

Learn about all 21 audit categories and their rules

Interpret results

Understand health scores, severity levels, and prioritization

Get Started

Website Auditing

Marketing Psychology

Skills & Integration

​Running audits

​Basic audit command

​Quick start examples

​Coverage modes explained

​Quick mode

​How it works

​Best for

CI/CD pipelines

Health monitoring

Rapid feedback

​Surface mode (Default)

​How it works

​Pattern detection example

​Best for

General audits

Template coverage

Regular monitoring

​Full mode

​How it works

​Override page limit

​Best for

Pre-launch audits

Deep analysis

Certification

​Coverage mode comparison

​Format options

​LLM format (Recommended for AI)

​Features

​Output structure

​Console format (Default)

​Features

​JSON format

​Features

​Example output

​HTML format

​Features

​Markdown format

​Features

​Format comparison

​Advanced options

​When to use

​When to use

​Page limit by coverage

​Output includes

​Combining options

​Two-step workflow

​Finding audit IDs

​Filtering reports

​Regression detection

​Diff output

​Common workflows

​Best practices

Start with surface

Use LLM format for automation

Save audit IDs

Refresh before comparisons

​Next steps

Audit categories

Interpret results

Build docs developers (and LLMs) love

Running audits

Basic audit command

Quick start examples

Coverage modes explained

Quick mode

How it works

Best for

Surface mode (Default)

How it works

Pattern detection example

Best for

Full mode

How it works

Override page limit

Best for

Coverage mode comparison

Format options

LLM format (Recommended for AI)

Features

Output structure

Console format (Default)

Features

JSON format

Features

Example output

HTML format

Features

Markdown format

Features

Format comparison

Advanced options

When to use

When to use

Page limit by coverage

Output includes

Combining options

Two-step workflow

Finding audit IDs

Filtering reports

Regression detection

Diff output

Common workflows

Best practices

Next steps