squirrelscan
GitHub

Configuration Overview

Understanding squirrelscan's configuration system

squirrelscan uses a layered configuration system that combines TOML config files and JSON settings to customize behavior.

Configuration is optional

squirrelscan works out of the box with sensible defaults. You only need configuration when you want to customize behavior.

Zero-config defaults:

  • Crawls up to 500 pages
  • 100ms delay between requests
  • Fetches robots.txt for sitemap discovery, but doesn’t enforce it (audits are owner-initiated)
  • Checks external links (cached 7 days)
  • Runs all rules (gap-analysis rules are opt-in)
  • Keeps the last 3 audits of a project; older ones are retired after a successful run
  • Cloud rules run when logged in, capped at 1000 credits per audit
  • Logged-in audits render pages in a cloud browser by default (one-time opt-in; --http to skip)
  • Console output format

Configuration system

squirrelscan has two separate configuration systems:

1. Project configuration (squirrel.toml)

What it controls:

  • How the crawler behaves (limits, delays, patterns)
  • Which audit rules run
  • Output format defaults
  • Per-rule options

File format: TOML

Scope: Project-specific (audits, crawling, rules)

Learn more: Project Configuration

2. CLI settings (settings.json)

What it controls:

  • Update channel (stable/beta)
  • Auto-update preferences
  • Notification settings
  • Feedback email

File format: JSON

Scope: CLI behavior (updates, notifications)

Learn more: CLI Settings

Configuration hierarchy

Settings are merged from multiple sources in this priority order:

1. Project config (squirrel.toml)

Priority: Highest (overrides everything)

Location: squirrelscan walks up from current directory to home directory looking for squirrel.toml

Current: /Users/you/projects/mysite/blog
Searches:
  1. /Users/you/projects/mysite/blog/squirrel.toml  ← Most specific
  2. /Users/you/projects/mysite/squirrel.toml
  3. /Users/you/projects/squirrel.toml
  4. /Users/you/squirrel.toml                       ← Least specific (home)

Create:

cd /path/to/project
squirrel init

Scope:

  • Crawler settings
  • Rule enable/disable
  • Rule options
  • Output format
  • External link checking

2. Local CLI settings (.squirrel/settings.json)

Priority: Medium

Location: .squirrel/settings.json in project directory

Create:

squirrel self settings set notifications false --local

Scope:

  • CLI notifications (project-scoped)
  • Update channel preferences (project-scoped)

Example:

{
  "notifications": false,
  "channel": "beta"
}

3. User CLI settings (~/.squirrel/settings.json)

Priority: Low

Location:

  • Unix/macOS: ~/.squirrel/settings.json
  • Windows: %LOCALAPPDATA%\squirrel\settings.json

Manage:

squirrel self settings show
squirrel self settings set channel beta

Scope:

  • Update channel (stable/beta)
  • Auto-update preferences
  • Notification settings
  • Feedback email
  • Dismissed update versions

4. Built-in defaults

Priority: Lowest

Scope: All settings have defaults

Project configuration

Project configuration is stored in squirrel.toml using TOML format.

Sections

SectionPurposeLearn More
[project]Project name, allowed domainsProject Settings
[crawler]Crawl limits, delays, patternsCrawler Settings
[rules]Enable/disable audit rulesRules Configuration
[external_links]External link checkingExternal Links
[classifier]The bundled page classifier that names where on a page a link sitsPage Classifier
[tech_detect]How much of each script bundle technology detection readsTechnology Detection
[output]Default output formatOutput Settings
[storage]How many audits a project keeps on diskStorage Settings
[cloud]Cloud features, spend limits, renderingCloud Settings
[security]Probing intensity and the probing time budgetSecurity configuration
[rule_options.*]Per-rule configurationRule Options
[plugins]Run your own audit rules, approved in your user settingsPlugins
smart_auditsCarry issues across partial re-audits (top-level boolean)Smart Audits

Smart Audits

smart_audits (top-level boolean) keeps issues from disappearing when you audit fewer pages than last time. Default: on when you are logged in (any plan), off for anonymous runs. Set it explicitly to override either way.

With it on, squirrelscan persists per-page issue state across audits (a local SQLite store keyed by site). On a partial re-audit:

  • re-crawled pages get fresh results that supersede their prior state,
  • un-crawled pages carry their last-known issues forward (tagged carried, with a “last seen” time) indefinitely, until you re-crawl them,
  • re-crawled pages where a check was skipped keep that check’s prior issues, tagged carried, when the check ran on other pages (for example perf/ttfb with no timing data, or a scan that stopped at its work cap). A rule that timed out or threw on a page carries all of its issues there. A check skipped on every page and a rule you disabled in config still close the issue. A check that does not apply to the page (no Link header, a URL with no file extension, a page that is not paginated, a small page) is not a skipped run: it closes the issue, since there is nothing left for it to find. A skip a fetch, parse or rendering problem could cause (an empty response, no body, no images) still carries it,
  • pages no audit has ever rendered (known from a sitemap or a rule’s page list, but never inside a run’s page budget) are tagged unrendered instead: nothing has observed them yet, so they have no “last seen” time and they are counted separately from carried findings. On a first audit every such finding is unrendered and the carried count is 0.
  • removed pages (404/410) have their issues closed.

The health score is then computed over the union of all known non-removed pages, so re-auditing a subset never inflates the score by hiding the issues on the pages you skipped. Reports show a coverage line (“audited N of M known pages”) and tag carried and unrendered findings.

What the coverage counts mean:

  • audited is the pages this run crawled, less the ones that came back 404 or 410.
  • known is every page the site’s store holds an active page record for: the pages any earlier run crawled and that have not since been removed, plus this run’s, plus the URLs this run found but never fetched because the host was rate limiting it. It is never lower than audited.
  • carried is the findings a previous run observed on pages this run did not crawl. They are keyed by the page’s URL, not by the page record, so a carried finding does not by itself prove the page is counted in known. A page whose record is missing from the store can carry findings while known equals audited. That is a gap in the store, not a statement that the finding is gone: the finding stays in the score and the report until the page is crawled again or comes back 404 or 410.

Carried findings do not expire on a timer: they last until you re-crawl the page (the fresh result replaces them) or it is removed. If a capped run rotates the pages it audits, the carried findings of the pages it left out stay in the score and show their last-seen time, so a stale one is visible rather than silently dropped.

smart_audits = true

When off, behaviour is unchanged (each audit reports only the pages crawled that run).

Quick Start

Create a config file:

squirrel init

This generates squirrel.toml with all available settings:

[project]
name = ""
domains = []

[crawler]
max_pages = 500
delay_ms = 100
timeout_ms = 30000
concurrency = 5
include = []
exclude = []
# ... more crawler options

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

[external_links]
enabled = true
cache_ttl_days = 7

[output]
format = "console"

[storage]
keep_audits = 3

[rule_options]
# Per-rule configuration

Example configurations

See Configuration Examples for common use cases:

  • High-volume crawl
  • Multi-domain project
  • CI/CD pipeline
  • Accessibility audit
  • Performance audit

CLI settings

CLI settings control squirrel’s own behavior (updates, notifications).

User settings

Global settings in ~/.squirrel/settings.json:

{
  "channel": "stable",
  "auto_update": true,
  "notifications": true,
  "user_feedback_email": "you@example.com",
  "dismissed_update_version": null
}

Manage:

# View all settings
squirrel self settings show

# Change update channel
squirrel self settings set channel beta

# Disable notifications
squirrel self settings set notifications false

Local settings

Project-scoped settings in .squirrel/settings.json:

{
  "notifications": false,
  "channel": "beta"
}

Manage:

# Set local (project-scoped) setting
squirrel self settings set notifications false --local

# View only local settings
squirrel self settings show --local

Use cases:

  • Disable notifications for specific project
  • Use beta channel for one project only
  • Different settings for work vs personal projects

Managing configuration

View configuration

Show effective config (merged from all sources):

squirrel config show

Show config file path:

squirrel config path

Modify configuration

Edit file directly:

nano squirrel.toml

Or use CLI:

squirrel config set crawler.max_pages 200

Preview changes:

squirrel config set crawler.max_pages 200 --dry-run

Validate configuration

Check for errors, including a [rule_options] table that names no rule, an option the rule does not take, or a value of the wrong type (see what happens to a mistake):

squirrel config validate

Output on success:

Config valid: /path/to/squirrel.toml

Output on error:

Invalid config: crawler.max_pages: Invalid input: expected number, received string

Configuration vs settings

AspectProject Config (squirrel.toml)CLI Settings (settings.json)
FormatTOMLJSON
PurposeAudit behaviorCLI behavior
ScopeCrawler, rules, outputUpdates, notifications
Managed bysquirrel init, squirrel configsquirrel self settings
LocationProject directory (walks up)~/.squirrel/ or .squirrel/
ExamplesMax pages, rule patterns, delaysUpdate channel, notifications

Next steps

Type to search…

↑↓ navigate↵ openesc close