Local audits with the CLI
Run a full website audit from your terminal, signed out with no account and no credits, then read the report in any format
Signed-out local audits cost nothing and need no login, up to the CLI’s 10,000-page cap per crawl. The squirrel CLI crawls a site on your machine and runs the deterministic audit rules against it, so you can check a live URL or your own localhost dev server without spending a thing. By the end of this guide you will have installed the CLI, run an audit, and read the report in the format that suits you.
Install the CLI
curl -fsSL --connect-timeout 10 --max-time 120 https://install.squirrelscan.com | bashiwr -useb https://install.squirrelscan.com/install.ps1 | iexbrew install --cask squirrelscan/tap/squirrelThe cask is macOS only. It installs a launcher that runs the regular installer on first use. brew upgrade does nothing for the CLI: update it with squirrel self update. See Homebrew for updates and uninstall.
This drops the binary at ~/.local/bin/squirrel and adds it to your PATH. With Homebrew, that happens on the first run, when the launcher runs the regular installer. Confirm it works:
squirrel self doctorFull install detail, including Alpine and musl notes, is in the Quickstart.
Run your first audit
Point squirrel audit at any URL:
squirrel audit https://example.comYou get a crawl and a scored report in the terminal:
✓ Audited 12 pages in 2.1s
──────────────────────────────────────────────────
SQUIRRELSCAN REPORT
https://example.com • 12 pages • 72/100 (C)
──────────────────────────────────────────────────
Core SEO (1 error, 3 warnings)
core/meta-description Meta Description (error)
✗ meta-description: Missing meta description
→ /about
→ /contact
──────────────────────────────────────────────────
87 passed • 12 warnings • 3 failed
──────────────────────────────────────────────────Logged out, audits default to the quick audit level: a fast local scan of the seed URL plus sitemaps, no account needed. For a wider crawl, raise the page limit or pick another level:
# Crawl up to 200 pages
squirrel audit https://example.com -m 200
# Smart sampling across URL patterns
squirrel audit https://example.com --level surfaceThe three levels are quick, surface, and full. Logged out, every level runs on your machine; the cloud checks need an account. See Audit levels for what each one crawls and checks.
Local and private hosts stay local
An audit of a host no squirrelscan server can reach runs and prints its report exactly as any other audit does. That covers localhost, loopback and link-local addresses, private ranges such as 192.168.1.10 or 10.0.0.5, and internal names such as box.local, a Laravel Valet or Herd site such as myapp.test, or anything under .internal or .lan. What changes is everything that would need a squirrelscan server to reach the address itself:
- The report is not published, so no shareable link is created and no site appears in your dashboard. The same applies to publishing it later with
squirrel report --publish. - The run is not registered, so it does not cost the audit base even when you are signed in.
- Cloud rendering is off for the run, including with
--render, and the crawl uses local HTTP fetching.
The reason is reachability, not policy: hosted services would have to fetch the address to screenshot it, render it, or re-audit it on a schedule, and they cannot reach your machine or your private network. The CLI prints one line saying the report stayed local.
What counts as local or private is the same wide test everywhere it matters (publishing, registering a run, the cloud render, a smart audit’s skipped rules, the default scheme): loopback, private ranges, link-local and carrier-grade NAT, the internal names above, and every special-use address, whatever it embeds. That includes NAT64 (64:ff9b::/96 and 64:ff9b:1::/48), 6to4 (2002::/16), Teredo and the other IETF assignments (2001::/23) and ISATAP forms, site-local and multicast IPv6, the IPv4 and IPv6 documentation ranges (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32), benchmarking, multicast and the reserved blocks. NAT64 and 6to4 are judged by their prefix, not by the IPv4 they embed: 64:ff9b::808:808 counts as local even though 8.8.8.8 is public, because it is translation space no hosted service is handed, while the crawl’s network guard judges it by the embedded address. A page on such an address has no public certificate and no public visitor, so squirrel audit [64:ff9b::a00:1] defaults to http:// and is not handed to a hosted service. The crawl’s own network guard is separate and unchanged: it decides what the crawl may connect to by address, and a redirect from a public start URL into any of these is still refused. The one place the narrower list applies is the private-network allowance for a start URL’s redirects, which follows only the private ranges and names, so a special-use literal never widens it.
Cloud analysis that works from pages the CLI has already crawled is unaffected, so a signed-in local audit still gets the AI summary, the technology change history, and the other content-based checks.
To get a shareable report for a site you are developing, audit it once it is on a public URL, such as a preview deployment.
Type a local host without a scheme and it is audited over http://, since most dev servers and local boxes serve plain http: squirrel audit myapp.test audits http://myapp.test/, and the same goes for localhost:3000, 192.168.1.10 and box.local. That covers every host the list at the end of Transport and delivery rules do not apply counts as local. Any other host without a scheme is audited over https://. Type the scheme to choose it yourself, for example squirrel audit https://myapp.test for a Valet or Herd site you have secured.
Transport and delivery rules do not apply
A dev server is plain HTTP on purpose, usually speaks HTTP/1.1, and sends no production caching or compression headers. Those things are decided by the server or CDN in front of the production site, not by your code, so the rules that judge them have nothing to say about a local or private host. On such a host they are skipped:
| Rule | What it judges |
|---|---|
security/https | Pages served over HTTPS |
security/hsts | The Strict-Transport-Security header |
security/http-to-https | HTTP URLs redirecting to HTTPS |
perf/http2 | HTTP/2 and HTTP/3 support |
perf/compression | Gzip or Brotli on HTML |
perf/asset-compression | Gzip or Brotli on scripts and stylesheets |
perf/cache-headers | Cache-Control on each page |
perf/bad-caching | Caching and validators across the site |
A skipped rule is not a pass and not a failure: it is left out of the score entirely, so a clean site on localhost scores what the same site scores behind a production edge, and one missing piece (no HTTPS, no compression, no caching policy) is not charged by several rules at once. The report says so once, under Scan details in Report detail at the end, instead of once per rule and page:
Local or private-network host: {count} transport and delivery rules do not apply here and are not scored ({rule names}).The JSON report carries the same fact as a top-level notApplicable object with reason: "private-target" and the skipped rules, and the llm format as a <not-applicable reason="private-target"> element. Inside the report data, each skipped check has status: "skipped" and skipReason: "private-target".
The host is classified from the URL you audit, not from where it redirects, with no DNS lookup, the same way the cloud handoff above is decided: localhost and anything under .localhost, loopback (127.0.0.0/8, ::1), private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7), link-local (169.254.0.0/16, fe80::/10), shared address space (100.64.0.0/10), internal names under .local, .internal, .lan, .home.arpa, .corp and similar, names under the reserved .test, .example and .invalid, under .localdomain and .home, and under .onion and .alt, which public DNS never resolves, and single-label names such as intranet. A public name is public even when it resolves to your machine, so localhost.example.com and a hosts-file entry for staging.example.com are audited like any public site.
Everything else still runs on a local host, including the rules that judge your markup or headers your app sets itself: security/mixed-content, security/form-https, security/csp, security/x-frame-options, perf/unminified-js and perf/ttfb.
To check transport and delivery, audit the site where it is actually delivered: the production URL or a preview deployment.
Set project defaults with a config file
Running the same audit repeatedly? Create a squirrel.toml so you do not retype flags:
squirrel initThis writes a config with sensible defaults. Edit it to pin the crawl scope and rule selection for the project:
[crawler]
max_pages = 100
include = ["/blog/*"]
exclude = ["/admin/*"]
[rules]
enable = ["*"]
disable = ["content/reading-level"]Now every squirrel audit in this folder uses those settings. See the Configuration reference for all options, and squirrel init for the command flags.
Read the report your way
The console output is for humans. For everything else, pick a format with -f and, optionally, write it to a file with -o:
| Format | Flag | Use it for |
|---|---|---|
console | (default) | Reading in the terminal |
json | -f json | CI pipelines and scripts |
markdown | -f markdown | Dropping into a README or PR |
llm | -f llm | Feeding a coding agent (compact, token-efficient) |
html | -f html | A visual report you open in a browser |
text | -f text | Plain text for logs and email |
# Machine-readable JSON to a file
squirrel audit https://example.com -f json -o report.json
# A visual HTML report
squirrel audit https://example.com -f html -o report.htmlEvery audit is stored in a local database, so you can re-read it later without re-crawling. The squirrel report command queries that history:
squirrel report --list # recent audits
squirrel report example.com # latest for a domain
squirrel report --severity error # errors only
squirrel report --category core,links # filter by categoryFor how the health score and grade are calculated, see Reports and scoring.
Use it inside a coding agent, locally
You do not need the cloud to put audits in front of an agent. Three local options, no login required:
Pipe the report straight in. The llm format is built for this:
squirrel audit https://example.com --format llm | claude "prioritize these fixes"Run the local MCP server. squirrel mcp starts a stdio MCP server that runs the audit engine on your machine, so an agent can call audits as tools while working offline:
squirrel mcpSigned-out local MCP audits cost nothing and need no account. Setup and the tool list are in squirrel mcp and the Hosted MCP server guide.
Install the skill. squirrel skills install teaches your agent the audit workflow so a prompt like “audit this site and fix the issues” just works. See Coding agent integration.
Gate CI on a local audit
Because it needs no login, a local audit is a clean CI check. --fail-on makes the command exit non-zero when a threshold trips:
squirrel audit https://staging.example.com --fail-on 'score<90' --fail-on 'severity>=error'Quote each expression, since shells read bare < and > as redirection. The full recipe for GitHub Actions, GitLab, and generic runners is in the CI guide.
Related
squirrel audit- every flag and audit levelsquirrel report- query and export stored audits- Reports and scoring - how the health score works
- Cloud audits - add AI analysis, rendering, and a shared tracker
- Coding agent integration - pipe, skill, and MCP workflows