Skip to main content
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
  • Respects robots.txt
  • Checks external links (cached 7 days)
  • Runs all rules except AI-powered ones
  • 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
[output]Default output formatOutput Settings
[rule_options.*]Per-rule configurationRule Options

​
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"

[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": "[email protected]",
  "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: 
squirrel config validate
Output on success: 
Config valid: /path/to/squirrel.toml
Output on error: 
Invalid config: crawler.max_pages: 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

Project Settings

Project name and allowed domains

Crawler Settings

Crawl limits, delays, and patterns

Rules Configuration

Enable/disable audit rules

Examples

Common configuration examples