audit

The audit command crawls a website and runs SEO rules to generate a report.

Usage

squirrel audit <url> [options]

Arguments

Options

Coverage Modes

Default coverage is auth-aware. Signed-in paid (Pro) accounts default to surface so the cloud-backed rules (AI/EEAT/blocking) and the editor’s summary run; free and anonymous runs default to quick (fast, no cloud calls, no credit spend). Pass --coverage (or set [crawler] coverage in config) to override either way. quick deliberately skips all networked cloud enrichment — use surface/full (or just sign in on a Pro plan) to run the full rule set.

Examples

Basic Audit

squirrel audit https://example.com

Quick Health Check

squirrel audit https://example.com -C quick

Full Comprehensive Audit

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

Crawl More Pages

squirrel audit https://example.com -m 200

Export to JSON

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

Generate HTML Report

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

Fresh Crawl (Ignore Cache)

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

Publishing to the Dashboard

When you’re signed in and online, every audit auto-publishes to your dashboard as unlisted — independent of cloud rendering or enrichment. You get a shareable link plus issue history with no extra flags. Not signed in (or --offline)? Nothing publishes.

Unlisted and private reports are free; only public reports cost 2 credits (charged once per report — flipping an existing report to public later charges the same 2 credits, then never again). The auto-publish default is unlisted, so it’s free.

# signed in → auto-publishes (unlisted, free) and prints the URL
squirrel audit https://example.com

Override the visibility for a run (publishing public costs 2 credits):

squirrel audit https://example.com --visibility public

Skip publishing for a single run (still runs online):

squirrel audit https://example.com --no-publish

Turn auto-publish off for the project in squirrel.toml:

[cloud]
publish = false

--publish is still accepted (now redundant when signed in) and forces a publish even if [cloud] publish = false. --publish and --no-publish cannot be combined.

Browser Rendering

When you’re logged in, audits render every page in a cloud browser by default (2 credits/page) - so JavaScript-heavy sites are audited against their fully rendered HTML. The first time this would spend credits the CLI asks once and remembers your answer.

Force plain HTTP for a run (no rendering, no render credits):

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

Force rendering for a run even if your config disables it:

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

For finer control, --render-mode auto renders only pages that need it (client-side-rendered shells) and uses fast plain HTTP for the rest. To set the behavior permanently, use render in [cloud] - see the browser rendering guide.

Fully Offline Audit

Run an audit with zero network calls beyond the site being audited — no cloud analysis, no publishing, no update checks, no telemetry. Results are stored in the local database as usual:

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

--offline cannot be combined with --publish or --render (both require cloud access and login).

Gate CI on Audit Results

Use --fail-on to fail a CI build when an audit regresses. The command exits with code 2 when any threshold trips (vs 1 for operational errors and 0 when everything passes), and prints a summary of what tripped:

# Fail if the overall score drops below 90, or any error-severity issue is found.
# Quote each expression — shells treat bare < and > as redirection.
squirrel audit https://example.com --fail-on 'score<90' --fail-on 'severity>=error'

# Comma-separated form, plus a per-category threshold
squirrel audit https://example.com --fail-on 'score<90,score:perf<80,warnings>0'

Supported metrics:

Operators: <, <=, >, >=, = — all five work on the numeric metrics (score, score:<category>, errors, warnings). For severity, = means the exact rank (e.g. severity=warning trips on warnings but not errors); use >= for “at least” (e.g. severity>=warning trips on warnings or errors).

The gate summary is written to stderr, so machine formats like --format json keep a clean stdout for piping. A malformed expression fails fast (exit 1) before any crawl runs.

Verbose Output

squirrel audit https://example.com -v

Output Formats

Console (default)

Human-readable output with colored issue severity:

squirrelscan v0.1.0
========================================
Auditing  https://example.com
Coverage  surface · max 100 pages
Config    defaults
Account   you@example.com · 500 credits
Dashboard https://app.squirrelscan.com

Crawled 12 pages

ISSUES

[high] Missing meta description
  → /about
  → /contact

[medium] Image missing alt text
  → /images/hero.png on /

[low] Non-HTTPS link
  → http://oldsite.com on /links

JSON

Machine-readable JSON for CI/CD pipelines and AI processing:

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

{
  "url": "https://example.com",
  "crawledAt": "2025-01-08T00:00:00Z",
  "pages": [...],
  "issues": [...],
  "stats": {
    "totalPages": 12,
    "issueCount": { "high": 2, "medium": 3, "low": 5 }
  }
}

HTML

Visual report you can open in a browser:

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

Crawl Behavior

The audit command manages crawl sessions intelligently:

Caching

SquirrelScan caches page content locally. On subsequent audits:

• 304 Not Modified: Uses cached content (fast)
• 200 OK: Fetches fresh content (slower)

Use --refresh to bypass the cache entirely.

Exit Codes

Configuration

The audit command respects settings from squirrel.toml:

[crawler]
max_pages = 100
delay_ms = 200
timeout_ms = 30000
include = ["/blog/*"]
exclude = ["/admin/*"]

[rules]
enable = ["*"]
disable = ["ai/*"]

See Configuration for all options.

Using with AI

Pipe JSON output to your LLM:

squirrel audit https://example.com -f json | claude "analyze this SEO report"

Or use with Claude Code’s MCP integration for interactive auditing.

Related

• Crawling - How the crawler works
• Configuration - Config file options
• squirrel report - View stored audit reports