Quickstart Guide

This guide will help you install the Market Research toolkit and run your first website audit in under 5 minutes.

Prerequisites

The toolkit works on:

macOS (Intel and Apple Silicon)
Linux (x64 and ARM64)
Windows (x64)

No other dependencies required. The squirrel CLI is a self-contained binary.

Install squirrel CLI

The squirrelscan CLI (squirrel) is the auditing engine. Install it based on your platform:

macOS & Linux

curl -fsSL https://squirrelscan.com/install | bash

This will:

Download the latest release binary for your platform
Install to ~/.local/share/squirrel/releases/{version}/
Create a symlink at ~/.local/bin/squirrel
Initialize settings at ~/.squirrel/settings.json

If ~/.local/bin is not in your PATH, add it to your shell configuration:

export PATH="$HOME/.local/bin:$PATH"

Then reload your shell: source ~/.bashrc (or ~/.zshrc for zsh)

Windows

Install using PowerShell (run as Administrator):

irm https://squirrelscan.com/install.ps1 | iex

This will:

Download the latest release binary
Install to %LOCALAPPDATA%\squirrel\
Add squirrel to your PATH

If using Command Prompt, you may need to restart your terminal for PATH changes to take effect.

Verify Installation

Check that squirrel is installed and accessible:

squirrel --version

You should see output like:

squirrel v1.18.0

If you get “command not found”, the installation directory is not in your PATH. Follow the PATH setup instructions above.

Run your first website audit

Now let’s audit a website. We’ll use the audit command, which handles crawling, analysis, and reporting in one step.

Initialize Project

First, create a project configuration:

squirrel init -n my-project

This creates a squirrel.toml configuration file in your current directory and sets up a local database at ~/.squirrel/projects/my-project.

The project name groups related audits together. If you’re auditing multiple versions of the same site (dev, staging, production), use the same project name so you can compare results.

Run Your First Audit

Let’s start with a surface audit — this intelligently samples your site by crawling one page per URL pattern:

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

Replace example.com with your actual website URL. Always include the protocol (https:// or http://).

The audit will:

Crawl up to 100 pages (surface mode default)
Analyze each page against 230+ audit rules
Check external links for availability
Generate an LLM-optimized report

This typically takes 30-90 seconds depending on site size.

Understanding Coverage Modes

The toolkit offers three coverage modes:

Mode	Pages	Behavior	Use Case
`quick`	25	Seed + sitemaps only, no link discovery	Fast health checks, CI pipelines
`surface`	100	One sample per URL pattern (default)	General audits
`full`	500	Crawl everything up to limit	Deep analysis, pre-launch checks

Surface mode is smart: it detects patterns like /blog/{slug} or /products/{id} and only crawls one example of each pattern. This makes it efficient for sites with many similar pages.

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

Why —format llm?

The llm format is a compact, structured output optimized for AI consumption:

40% smaller than verbose XML formats
Grouped by category for easier navigation
Includes recommendations with specific fix suggestions
Lists broken links separately for quick triage

Other formats are available (console, json, html, markdown), but llm is recommended when working with AI agents.

Interpret results

The audit output includes several key sections:

Health Score

Your site gets an overall score from 0-100 with a letter grade:

Score	Grade	Status
95-100	A+	Excellent
90-94	A	Very Good
85-89	B+	Good
80-84	B	Acceptable
70-79	C	Needs Improvement
60-69	D	Poor
0-59	F	Critical Issues

A complete and fixed site should score 95+ (Grade A) with --coverage full.

Category Breakdowns

The score is broken down by category:

Core SEO: Meta tags, titles, descriptions, structured data
Technical SEO: Crawlability, URLs, redirects, canonicals
Content: Headings, images, readability, structure
Security: HTTPS, leaked secrets, security headers
Performance: Page speed, resource usage, mobile-friendliness
Accessibility: Alt text, color contrast, keyboard navigation

Issue Severity

Each issue has a severity level:

Error: Critical problems that should be fixed immediately
Warning: Important issues that impact quality
Notice: Minor issues or suggestions for improvement

Issues also have a rank (1-10) indicating their impact on overall health.

Affected URLs

For each issue, you’ll see which pages are affected:

<issue>
  <rule>missing-h1</rule>
  <severity>error</severity>
  <rank>8</rank>
  <count>12</count>
  <sample_urls>
    <url>/about</url>
    <url>/contact</url>
    <url>/blog/post-1</url>
  </sample_urls>
</issue>

Broken Links

The audit separately lists broken links found:

Internal broken links: Links to pages on your site that don’t exist
External broken links: Links to third-party sites that return errors

Recommendations

Each issue includes actionable recommendations:

What the problem is
Why it matters
How to fix it

Rule Documentation

For detailed information about any rule, visit:

https://docs.squirrelscan.com/rules/{category}/{rule-id}

For example:

https://docs.squirrelscan.com/rules/links/external-links

Apply psychology frameworks

Now that you’ve identified technical issues, apply marketing psychology to understand and prioritize fixes.

Common Issue → Psychology Mapping

Technical Issue	Psychology Principle	Why It Matters
Slow page load	Activation Energy	High friction prevents action. Users abandon slow sites.
No testimonials	Social Proof	People trust what others validate. Missing social proof reduces conversions.
Complex form	Hick’s Law	More fields = slower decisions = more abandonment.
Weak CTA	BJ Fogg Model	Need clear prompt. “Click here” < “Start your free trial”
No urgency	Loss Aversion	People need a reason to act now vs. later.
Poor mobile UX	Opportunity Cost	Mobile users are majority traffic. Bad mobile = lost customers.
Missing meta	Mere Exposure Effect	Search/social snippets are first touchpoints. Bad snippet = fewer clicks.

Prioritization Framework

When deciding what to fix first, consider:

Severity × Traffic: Fix errors on high-traffic pages first
Effort × Impact: Quick wins (low effort, high impact) before large projects
Conversion pages: Prioritize landing pages, pricing, signup flows
Compounding value: SEO and content fixes compound over time — start early

Example: Applying Mental Models

Let’s say your audit found:

Missing H1 on 12 pages
No meta descriptions on 8 pages
Complex 15-field signup form
No customer testimonials
HTTP links (not HTTPS)

Apply psychology:

Missing H1 (Jobs to Be Done)

H1 tells users what job this page does. Without it, users don’t know if they’re in the right place. Fix: Add clear, outcome-focused H1s that describe the job to be done.

No meta descriptions (Availability Heuristic)

Search results are first impressions. Poor snippet = fewer clicks. Fix: Write compelling meta descriptions that make success feel achievable.

Complex form (Hick's Law + Activation Energy)

15 fields = high friction = abandonment. Fix: Reduce to 3-5 essential fields. Use progressive disclosure for optional data.

No testimonials (Social Proof + Authority)

HTTP links (Security + Trust)

Mixed content warnings reduce trust. Fix: Update all links to HTTPS. This is also important for SEO rankings.

Using the Marketing Psychology Skill

When working with AI agents, you can invoke the marketing psychology skill directly:

"Apply marketing psychology principles to this landing page audit.
Focus on conversion optimization using mental models."

The agent will:

Identify relevant mental models for your specific situation
Explain the psychology behind buyer behavior
Provide concrete implementation recommendations
Ensure ethical application of persuasion techniques

Next steps

Congratulations! You’ve completed your first audit and learned how to interpret results through a psychological lens.

Implement Fixes

Now it’s time to fix the issues:

Start with errors: Fix critical issues first (missing H1s, broken links, security)
Parallelize content fixes: For issues affecting many files (alt text, headings), fix multiple files simultaneously
Test changes: Deploy to staging/preview before production
Re-audit: Run another audit to verify improvements

# After deploying fixes, re-audit
squirrel audit https://example.com --refresh --format llm

The --refresh flag ignores cached data and fetches everything fresh.

Compare Before & After

To see what changed between audits:

# List recent audits to get IDs
squirrel report --list

# Compare current state against baseline
squirrel report --diff <baseline-audit-id> --format llm

# Or compare against previous audit of same domain
squirrel report --regression-since example.com --format llm

Diff mode highlights:

New issues that appeared
Fixed issues that were resolved
Changed scores by category

Iteration Loop

Website optimization is iterative:

Audit → Prioritize → Fix → Test → Re-audit → Repeat

Keep iterating until:

Score reaches 95+ (Grade A)
All errors are resolved
All warnings are fixed or documented as requiring human review
Full coverage audit confirms comprehensive health

Don’t stop at “good enough.” A score of 95+ with full coverage is the gold standard for a properly optimized site.

Advanced Options

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

Continuous Monitoring

Integrate audits into your workflow:CI/CD Integration: Run quick audits on preview deployments

squirrel audit $PREVIEW_URL -C quick --format llm

Scheduled Audits: Run weekly surface audits to catch regressions

# Add to cron or CI schedule
squirrel audit https://example.com --format llm --output weekly-audit.txt

Pre-Launch Checks: Run full audits before major releases

squirrel audit https://staging.example.com -C full --format llm

Learn More

Now that you’ve mastered the basics, explore:

Rule Reference: docs.squirrelscan.com — Learn about all 230+ audit rules
Marketing Psychology: Review the 70+ mental models in the toolkit
Configuration: Customize audit behavior with squirrel.toml
CLI Reference: Run squirrel --help for complete command documentation

Getting Help

If you encounter issues:

# Run health checks
squirrel self doctor

# Send feedback to squirrelscan team
squirrel feedback

# Check version
squirrel --version

# Update to latest version
squirrel self update

Common Issues:

Command not found: Ensure ~/.local/bin (macOS/Linux) or %LOCALAPPDATA%\squirrel (Windows) is in your PATH
Permission denied: Run chmod +x ~/.local/bin/squirrel (macOS/Linux)
Invalid URL: Always include protocol: https://example.com not example.com

What’s Next?

You’re now ready to audit websites, apply psychological principles, and optimize for both technical performance and conversion effectiveness. Remember:

Always audit live websites for accurate results
Use surface mode for general audits, full mode for comprehensive checks
Iterate until scores reach 95+ with full coverage
Apply psychology to understand why fixes matter and how to prioritize
Re-audit frequently to catch regressions

The Market Research toolkit is designed to work seamlessly with AI agents. When requesting audits, agents will automatically handle installation, configuration, execution, fix implementation, and iteration.

Get Started

Website Auditing

Marketing Psychology

Skills & Integration

Quickstart Guide

Quickstart Guide

Prerequisites

macOS & Linux

Windows

Verify Installation

Initialize Project

Run Your First Audit

Understanding Coverage Modes

Why —format llm?

Health Score

Category Breakdowns

Issue Severity

Affected URLs

Broken Links

Recommendations

Rule Documentation

Common Issue → Psychology Mapping

Prioritization Framework

Example: Applying Mental Models

Using the Marketing Psychology Skill

Implement Fixes

Compare Before & After

Iteration Loop

Advanced Options

Continuous Monitoring

Learn More

Getting Help

What’s Next?

Build docs developers (and LLMs) love

Get Started

Website Auditing

Marketing Psychology

Skills & Integration

​Quickstart Guide

​Prerequisites

​macOS & Linux

​Windows

​Verify Installation

​Initialize Project

​Run Your First Audit

​Understanding Coverage Modes

​Why —format llm?

​Health Score

​Category Breakdowns

​Issue Severity

​Affected URLs

​Broken Links

​Recommendations

​Rule Documentation

​Common Issue → Psychology Mapping

​Prioritization Framework

​Example: Applying Mental Models

​Using the Marketing Psychology Skill

​Implement Fixes

​Compare Before & After

​Iteration Loop

​Advanced Options

​Continuous Monitoring

​Learn More

​Getting Help

​What’s Next?

Build docs developers (and LLMs) love

Quickstart Guide

Prerequisites

macOS & Linux

Windows

Verify Installation

Initialize Project

Run Your First Audit

Understanding Coverage Modes

Why —format llm?

Health Score

Category Breakdowns

Issue Severity

Affected URLs

Broken Links

Recommendations

Rule Documentation

Common Issue → Psychology Mapping

Prioritization Framework

Example: Applying Mental Models

Using the Marketing Psychology Skill

Implement Fixes

Compare Before & After

Iteration Loop

Advanced Options

Continuous Monitoring

Learn More

Getting Help

What’s Next?