squirrelscan

Files (5)

• SKILL.md
• openai.yaml · agents/
• icon-large.png · assets/
• icon-small.svg · assets/
• entity-map-fixes.md · references/

SKILL.md (first lines)

# squirrelscan CLI

squirrelscan is a website audit tool built for AI agents. It answers "what's wrong with this website and how do I fix it": it crawls a site like a search engine, analyzes every page against 300+ rules in 22 categories (SEO, performance, security, accessibility, content, structured data, agent experience, and more), and returns a health score plus concrete, fixable issues. Use it whenever a user wants their site checked, ranked better, faster, or healthier, before/after a deploy, or in CI.

It ships as a single CLI binary, `squirrel`, for macOS, Windows, and Linux. This skill covers operating it: installing, authenticating, running audits, publishing reports, cloud features, and MCP integration. For the full fix-the-website workflow (audit, map issues to code, fix, re-audit), use the companion `audit-website` skill.

## Links

- Website: [squirrelscan.com](https://squirrelscan.com)
- Docs: [docs.squirrelscan.com](https://docs.squirrelscan.com)
- Rule reference: `https://docs.squirrelscan.com/rules/{rule_category}/{rule_id}`
- Dashboard (cloud account, audit history, credits): [app.squirrelscan.com](https://app.squirrelscan.com)

## Install

Download and install instructions: [squirrelscan.com/download](https://squirrelscan.com/download)

Prefer a package manager where one fits:

```bash
brew install --cask squirrelscan/tap/squirrel                         # Homebrew, macOS only
```

Otherwise use the installer from the download page above (macOS, Linux, Windows). Do not pipe it into a shell: download the script, read it, then run it. When an agent runs the install, fetch it as `https://install.squirrelscan.com/install.sh?source=agent` (`/install.ps1?source=agent` on Windows) so the install is counted as agent-driven; the script is the same either way. The download page has the current install command, and [docs.squirrelscan.com/quickstart](https://docs.squirrelscan.com/quickstart) covers the same steps.

Verifying: the download page lists a SHA-256 checksum for each release binary, and the installer checks each binary against the checksum in the release manifest before it installs (also when it falls back to the `install.squirrelscan.com` mirror). To check a binary by hand, compare `shasum -a 256 <file>` with the value on the download page. The installer script itself has no separate checksum; inspect it before you run it.

The binary installs to `~/.local/bin/squirrel`. With Homebrew, the cask installs only a small launcher: the first run downloads the CLI with the regular installer. Verify with:

```bash
squirrel --version
```

Keep it current, however it was installed:

```bash
squirrel self update
```

`brew upgrade` does not update the CLI (Homebrew only owns the launcher), so use `squirrel self update`. To uninstall a Homebrew install: `brew uninstall --cask squirrel` (add `--zap` to remove `~/.squirrel` as well).

To set the CLI up for the user's agent, run `squirrel setup` (optional sign-in, agent skills for Claude Code, Codex, Cursor and more, auto-update). An agent can also fetch and follow https://docs.squirrelscan.com/agent-setup/prompt.md.

If `squirrel` is not found, ensure `~/.local/bin` is in PATH, or reinstall from the download page.

An install is not finished until the first audit has run. Right after installing, run `squirrel audit <the user's site> --format llm` (ask for the URL if the project does not make it obvious) and show the user the result: the score and the top issues. Do not stop at "installed".

## Command overview

| Command | Purpose |
|---------|---------|
| `squirrel audit <url>` | Crawl + analyze + report in one step |
| `squirrel crawl <url>` | Crawl only (no analysis) |
| `squirrel analyze` | Run audit rules on a stored crawl |
| `squirrel report [id]` | Query, render, diff, and publish stored reports |
| `squirrel entities` | Query the site's structured-data entity graph; filter, export, diff |
| `squirrel init` | Create `squirrel.toml` project config |
| `squirrel config` | Show or edit configuration |
| `squirrel auth` | login / logout / status / whoami |
| `squirrel keys` | Mint, list, revoke org API keys |
| `squirrel credits` | Cloud credit balance + feature pricing |
| `squirrel mcp` | Run the local MCP server (stdio) |
| `squirrel skills` | Check, install, update or remove these agent skills |
| `squirrel self` | install / update / doctor / disk / completion / version / settings / uninstall |
| `squirrel feedback` | Send feedback to the squirrelscan team |

Every command supports `--help`.

## Quickstart

```bash
squirrel init -n my-project        # optional: project config in cwd
squirrel audit https://example.com --format llm
```

- Signed out, or with `--offline`, an audit runs entirely on your machine, needs no account and costs nothing. Signed in, every audit is billed in credits, at every level (see Cloud features and credits below).
- Use `--format llm` when an agent is reading the output: it is a compact, token-optimized format built for LLMs.
- Audits are cached in a local project database; `squirrel report` re-renders without re-crawling.

### Exit codes and audits that did not run

| Code | Meaning |
|------|---------|
| `0` | The audit ran |
| `1` | Error: an invalid URL, a failed crawl, a site that answered with an error |
| `2` | A `--fail-on` threshold tripped |
| `3` | Blocked: the audited page was refused, so nothing was audited. Status `blocked`, no score |
| `4` | The start URL redirected to another site and the run was not told to follow it. Status `redirected` |
| `5` | The start URL could not be reached (DNS, TLS, refused or reset connection, timeout). Status `unreachable` |

Codes `4` and `5`, and `3` for a bare 403 or 429, need squirrel 0.0.142 or later; `3` for a WAF or bot manager challenge needs 0.0.140. On an older version run `squirrel self update` first. A CI step that treated only `1` as failure must accept `3`, `4` and `5` too. None of these is a score: never report a site as clean, or as scoring zero, because of one. Docs: https://docs.squirrelscan.com/cli/audit#exit-codes

**Blocked (`3`).** A WAF or bot manager served a challenge or block page, or the server answered the audited page with a bare 403 or 429. The report carries `status: "blocked"`, `statusReasonCode` and a reason. When a provider was identified, `wafBlocked.seed.code` is `blocked_by_<provider>` (`blocked_by_waf` when none was named), and other blocked pages are left out of every rule and the score and listed under `wafBlocked.pages`. Tell the user the site refused the crawler, not that it has no issues. When the report says the host rate limited the crawler (429 or 430), it is throttling, not bot protection: allowlisting a crawler will not help. Crawl more slowly (`[crawler] per_host_concurrency = 1` and `per_host_delay_ms = 500`, or a larger `max_backoff_ms`) or retry later. A bare 403 or 429 with no throttle record is the generic case (bot protection, a firewall, an auth wall or rate limiting). For a WAF or bot manager block, offer the ways through: allow the `SquirrelScan` user agent in the WAF, add the headers it trusts with `-H`, authenticate, or run from a network the site trusts (datacenter and CI addresses are challenged more often than a laptop). Do not set `user_agent` or bypass the protection on a site the user is not authorized to audit. Docs: https://docs.squirrelscan.com/guides/failed-audits#blocked-by-waf

**Redirected (`4`).** The start URL's redirect chain is resolved before any crawl. A redirect within one site (`http` to `https`, apex to `www`) is followed silently. One to another registrable domain (a link shortener, a launch domain) is not: the run exits `4` and prints a `redirected` report with `reason`, `originalUrl`, `finalUrl`, `redirectChain` and `rerunCommand` (shape in `audit-website/references/OUTPUT-FORMAT.md`). The destination is the redirector's choice, not the user's, so relay it and run `rerunCommand` only after the user confirms that is the site they meant. Never add `--follow-redirect`, `[crawler] follow_redirect = true` or `-y` on your own: `-y` approves credit spend only and does not follow. A loop, a chain past 5 hops (`too-many`) and a refused hop are never followed. Only `loop` and `refused` have no `rerunCommand`; for `too-many` it audits the destination the chain was heading to, not the original URL. Only the destination's origin and path are audited (query, fragment and credentials are dropped), so a destination that needs them must be typed directly. Over MCP, the local `audit_website` tool answers `confirmation_required` with `reason: "redirect"` and the destination until it is called again with `followRedirect: true`; `confirm: true` alone does not follow. A followed redirect is recorded as `meta.originalUrl` and `meta.redirectChain`. Docs: https://docs.squirrelscan.com/cli/audit#start-urls-that-redirect

**Unreachable (`5`).** With `-f json`, `xml` or `llm` the report still arrives, with `status: "unreachable"` and `statusReasonCode` (`dns`, `tls`, `connection`, `timeout` or `unknown`). Tell the user the site is down or the URL is wrong; retrying with the same URL does not change it. Docs: https://docs.squirrelscan.com/cli/audit#unreachable-start-urls

### Audit levels

A level is a named set of audit settings: pages, crawl strategy, cloud checks, rendering, external link checks and probing. The CLI, both MCP servers, the API and the dashboard use the same three.

| Level | Pages | Behavior |
|-------|-------|----------|
| `quick` | 25 | The URL and its sitemaps, no link following. No cloud checks. The signed-out default |
| `surface` | 100 | Follows links, one page per URL pattern first (`/blog/{slug}` crawled once). Cloud checks and external link checks. The signed-in default |
| `full` | 500 | Every page it can reach, up to the page budget, with the cloud checks |

```bash
squirrel audit https://example.com --level quick --format llm
squirrel audit https://example.com --level full -m 500 --format llm
```

- `--level` needs squirrel 0.0.108 or later; on an older version run `squirrel self update` first. `--coverage` / `-C` is the older name and still works (`fast` means quick).
- Quick skips the cloud checks, but signed in it is still a billed cloud audit like any level: 50 credits plus 2 per audited page, with the pages that need JavaScript rendered in the cloud browser, so up to 100 credits for 25 pages. `--http` skips the browser, not the page charge. Only a signed-out or `--offline` audit is charge-free.
- In the cloud (dashboard, API, hosted MCP), Full is Pro and Team. A Free organization's `full` request still runs, but samples one page per URL pattern first, the way surface does, up to 500 pages, and the response says so (`levelNotice` in the API, `level_notice` from the hosted MCP server).

Docs: https://docs.squirrelscan.com/guides/audit-levels

From squirrelscan/skills, MIT.

More from squirrelscan/skills