Configuration Overview

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 (gap-analysis rules are opt-in)
• Cloud rules run when logged in, capped at 200 credits per audit
• 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

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

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

Next Steps

Related

• init - Create config file
• config - Manage config
• self settings - Manage CLI settings