Skip to content
This repository was archived by the owner on Jun 14, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion cli/audit.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ squirrel audit <url> [options]
| `--publish` | `-p` | Publish report to reports.squirrelscan.com (costs 2 credits) | `false` |
| `--visibility` | | Visibility: `public`, `unlisted`, `private` | `public` |
| `--yes` | `-y` | Skip confirmation prompts (e.g. cloud credit spend) | `false` |
| `--render` | | Render pages with a cloud browser for this run ([uses credits](/guides/browser-rendering); requires login) | `false` |
| `--render` | | Force cloud browser rendering for this run ([uses credits](/guides/browser-rendering); requires login) | auto |
| `--http` | | Force plain HTTP for this run - never render, never spend render credits | auto |
| `--offline` | | Run fully offline: skip cloud features, publishing, and telemetry | `false` |

### Coverage Modes
Expand Down Expand Up @@ -114,6 +115,24 @@ squirrel audit https://example.com --publish --visibility unlisted
Publishing requires authentication. Run `squirrel auth login` first.
</Note>

### Browser Rendering

When you're **logged in, audits render every page in a cloud browser by default** (2 credits/page) - so JavaScript-heavy sites are audited against their fully rendered HTML. The first time this would spend credits the CLI asks once and remembers your answer.

Force plain HTTP for a run (no rendering, no render credits):

```bash
squirrel audit https://example.com --http
```

Force rendering for a run even if your config disables it:

```bash
squirrel audit https://example.com --render
```

`--render` and `--http` are mutually exclusive. To set the behavior permanently, use `rendering` in `[cloud]` - see the [browser rendering guide](/guides/browser-rendering).

### Fully Offline Audit

Run an audit with zero network calls beyond the site being audited — no cloud
Expand Down
2 changes: 1 addition & 1 deletion cli/report.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@ Filter reports by these categories:
- `video` - Video optimization
- `analytics` - Analytics
- `eeat` - E-E-A-T signals
- `adblock` - Adblock detection
- `blocking` - Ad-blocker & privacy-filter impact (`adblock` still accepted)

## Exit Codes

Expand Down
4 changes: 2 additions & 2 deletions cloud/credits.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Top up: https://squirrelscan.com/account/credits
| AI page analysis | 1 per page | [`ai/llm-parsability`](/rules/ai/llm-parsability), [`ai/page-type-match`](/rules/ai/page-type-match) |
| Site type detection | 5 per audit | [`ai/site-type`](/rules/ai/site-type) |
| Authority signals | 1 per page | [`eeat/authority-signals`](/rules/eeat/authority-signals) |
| Adblock/privacy check | 5 per audit | All three [adblock rules](/rules/adblock) share one check |
| Blocking check (ad + privacy) | 5 per audit | All three [Blocking rules](/rules/adblock) share one check |
| Dead link checking | 1 per 100 URLs | [`links/dead-links`](/rules/links/dead-links) |
| Browser rendering | 2 per page | [Cloud rendering](/cloud/rendering) |
| Keyword gaps | 25 per audit | [`gaps/keywords`](/rules/gaps/keywords) (opt-in) |
Expand All @@ -60,7 +60,7 @@ Three guardrails keep an audit from spending more than you expect:

```toml squirrel.toml
[cloud]
max_credits_per_audit = 200 # hard cap per audit; 0 = unlimited
max_credits_per_audit = 1000 # hard cap per audit; 0 = unlimited
confirm_threshold = 50 # estimates above this prompt before spending
enabled = true # master switch for all cloud features
```
Expand Down
22 changes: 20 additions & 2 deletions cloud/rendering.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,33 @@ description: "How cloud browser rendering works under the hood"
icon: "globe"
---

By default the crawler fetches pages with plain HTTP - fast, free, and accurate for server-rendered sites. Sites that build their content with JavaScript (SPAs, client-side frameworks) can look nearly empty to a plain fetch, which skews every content rule.
A plain HTTP fetch is fast, free, and accurate for server-rendered sites - but sites that build their content with JavaScript (SPAs, client-side frameworks) can look nearly empty to it, which skews every content rule.

Cloud browser rendering fixes that: each page is loaded in a **real headless browser** in the cloud, and the fully rendered DOM is returned to your local crawler. Everything downstream - parsing, rules, reports - works exactly as it does with plain HTTP, just on the post-JavaScript HTML.

<Note>Looking for setup instructions? See the [browser rendering guide](/guides/browser-rendering). This page explains how the service behaves.</Note>

## When it runs

Rendering follows your login state by default:

- **Logged in** - audits render every page in the cloud automatically. The first time this would spend credits, the CLI asks once (`Render pages in the cloud? [Y/n]`) and remembers your choice in `squirrel self settings` - it never asks again.
- **Logged out, `--offline`, or you declined the prompt** - plain HTTP, no credits.

Override the default any time:

| Want | How |
|------|-----|
| Plain HTTP for one run | `squirrel audit <url> --http` |
| Render for one run | `squirrel audit <url> --render` |
| Always plain HTTP for a project | `rendering = "http"` in `[cloud]` |
| Always render for a project | `rendering = "browser"` in `[cloud]` |

Flags win over config, and config wins over the auto default. Non-interactive runs (CI, agents, pipes) never prompt - they render only if you've already consented or set `rendering = "browser"`, otherwise they use plain HTTP.

## Cost

**2 credits per page rendered.** A 100-page crawl with rendering costs 200 credits, so mind your [per-audit cap](/cloud/credits#spend-controls) - the default cap of 200 covers rendering for about 100 pages and nothing else. The crawl progress line shows the running spend:
**2 credits per page rendered.** A 100-page crawl with rendering costs 200 credits, so mind your [per-audit cap](/cloud/credits#spend-controls) - the default cap of 1000 covers rendering for about 500 pages. The crawl progress line shows the running spend:

```
Crawling (cloud-rendered) 34/100 · ~68 credits
Expand Down
2 changes: 1 addition & 1 deletion cloud/rules.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Cloud rules are regular audit rules that need data your machine doesn't have - A
| [`gaps/keywords`](/rules/gaps/keywords) | Keywords competitors rank for that you don't | 25 credits per audit, **opt-in** |
| [`gaps/content`](/rules/gaps/content) | Topic clusters with search demand you don't cover | 25 credits per audit, **opt-in** |

The three adblock rules share a single 5-credit blocklist check per audit - enabling all three costs the same as enabling one.
The three [Blocking](/rules/adblock) rules (IDs keep the `adblock/` prefix) share a single 5-credit blocklist check per audit - enabling all three costs the same as enabling one. They report as warnings in their own report section.

The two gap-analysis rules are **disabled by default** because of their cost. Enable them explicitly:

Expand Down
15 changes: 10 additions & 5 deletions configuration/cloud.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ All cloud settings are no-ops when you're not logged in - cloud rules simply rep
```toml squirrel.toml
[cloud]
enabled = true # master switch for all cloud features
max_credits_per_audit = 200 # hard spend cap per audit; 0 = unlimited
max_credits_per_audit = 1000 # hard spend cap per audit; 0 = unlimited
confirm_threshold = 50 # estimates above this prompt for confirmation
batch_size = 20 # pages per cloud service request
rendering = "http" # "http" (default) or "browser"
# rendering # omit = auto (render when logged in); set "http" or "browser" to force
render_concurrency = 6 # concurrent browser-render jobs (1-8)
```

Expand All @@ -27,7 +27,7 @@ Master switch. Set to `false` to disable all cloud calls for this project - clou

### `max_credits_per_audit`

**Default:** `200`
**Default:** `1000`

Hard cap on credits a single audit may spend. When the estimate exceeds the cap, cloud work is truncated deterministically and the rules that didn't run report `skipped` with reason `credit-cap-reached`. Set to `0` for unlimited.

Expand All @@ -45,9 +45,14 @@ Pages per request to per-page cloud services. Lower it only if you hit request-s

### `rendering`

**Default:** `"http"`
**Default:** unset (auto)

Crawl fetch mode. `"browser"` renders every page with a cloud headless browser at **2 credits per page** - see the [browser rendering guide](/guides/browser-rendering). The `--render` flag on `squirrel audit` enables it for a single run without changing config.
Crawl fetch mode. Leave it unset and squirrelscan decides: **logged-in users render every page in a cloud browser; logged-out runs use plain HTTP**. The first time an auto-render would spend credits, the CLI asks once and remembers your answer (`squirrel self settings`). Set it explicitly to override the auto behavior:

- `"http"` - always plain HTTP; never render, never prompt (no credits)
- `"browser"` - always render every page at **2 credits per page**

The `--render` and `--http` flags on `squirrel audit` force rendering on or off for a single run and always win over config. See the [browser rendering guide](/guides/browser-rendering).

### `render_concurrency`

Expand Down
3 changes: 2 additions & 1 deletion configuration/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ squirrelscan works out of the box with sensible defaults. You only need configur
- 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
- Cloud rules run when logged in, capped at 1000 credits per audit
- Logged-in audits render pages in a cloud browser by default (one-time opt-in; `--http` to skip)
- Console output format

## Configuration System
Expand Down
2 changes: 1 addition & 1 deletion configuration/rule-options.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -623,7 +623,7 @@ If 90%+ of crawled pages are noindexed → `warn` (possible misconfiguration)

---

### Adblock Rules
### Blocking Rules

#### `adblock/element-hiding`

Expand Down
13 changes: 7 additions & 6 deletions configuration/rules.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -511,13 +511,13 @@ disable = [] # Remove ai/* from disable list

---

### Adblock Detection
### Blocking

**ID:** `adblock/*`
**Rules:** 2
**Description:** Adblock filter impact
**Rules:** 3
**Description:** Ad-blocker & privacy-filter impact (ad blocking + privacy blocking)

Element hiding, blocked tracking domains.
Element hiding, blocked tracking links, and privacy-filter matches. Reported as warnings in their own report section.

**Enable:**
```toml
Expand All @@ -526,8 +526,9 @@ enable = ["adblock/*"]
```

**Rules:**
- `adblock/element-hiding` - Elements hidden by adblockers
- `adblock/blocked-links` - Links to blocked domains
- `adblock/element-hiding` - Elements hidden by adblockers (ad blocking)
- `adblock/blocked-links` - Links to blocked domains (ad blocking)
- `adblock/privacy-blocked` - Trackers EasyPrivacy would block (privacy blocking)

---

Expand Down
2 changes: 1 addition & 1 deletion docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -406,7 +406,7 @@
]
},
{
"group": "Adblock Detection",
"group": "Blocking",
"pages": [
"rules/adblock/index",
"rules/adblock/element-hiding",
Expand Down
28 changes: 20 additions & 8 deletions guides/browser-rendering.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,36 +9,48 @@ Browser rendering solves this: pages are loaded in a real headless browser in th

<Note>Browser rendering is a [cloud feature](/cloud) - it requires login and costs **2 credits per page**. See [how it works under the hood](/cloud/rendering).</Note>

## Try it on one run
## It's automatic when you're logged in

```bash
squirrel auth login # once
squirrel audit https://example.com --render
squirrel audit https://example.com
```

`--render` uses the cloud browser for this run only. The crawl progress shows the running credit spend:
Once you're logged in, audits render every page in the cloud by default. The first time this would spend credits, the CLI asks once and remembers your answer - so you opt in knowingly and never get prompted again. The crawl progress shows the running credit spend:

```
Crawling (cloud-rendered) 34/100 · ~68 credits
```

## Make it permanent for a project
Logged-out runs (and `--offline`) always use plain HTTP and cost nothing.

If a site always needs rendering, set it in `squirrel.toml`:
## Turn it off for one run

If a site is server-rendered and you don't want to spend render credits:

```bash
squirrel audit https://example.com --http
```

`--http` forces plain HTTP for that run. The opposite, `--render`, forces rendering even when your config disables it. The two are mutually exclusive.

## Make the choice permanent for a project

Pin the behavior in `squirrel.toml` so it never depends on login state or the prompt:

```toml squirrel.toml
[cloud]
rendering = "browser" # default: "http"
rendering = "browser" # always render; use "http" to always skip
```

Every audit of this project now renders pages, no flag needed.
Setting `rendering` explicitly overrides the auto default - no prompt, every audit of this project behaves the same.

## Watch your page count

At 2 credits per page, rendering is the most spend-sensitive cloud feature. Two settings to keep in mind:

- `--max-pages` / `[crawler] max_pages` - fewer pages, fewer credits.
- `[cloud] max_credits_per_audit` (default **200**) - the hard cap. A 100-page rendered crawl alone hits it; raise it or cap your pages.
- `[cloud] max_credits_per_audit` (default **1000**) - the hard cap. It covers rendering for about 500 pages; raise it or cap your pages for larger rendered crawls.

```toml squirrel.toml
[cloud]
Expand Down
2 changes: 1 addition & 1 deletion reports.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -424,7 +424,7 @@ squirrel report --category core,links,images
- `video` - Video optimization (schema, thumbnails)
- `analytics` - Analytics tracking (GTM, consent)
- `eeat` - E-E-A-T signals (author, expertise, trust)
- `adblock` - Adblock detection
- `blocking` - Ad-blocker & privacy-filter impact (`adblock` still accepted)

### Combined Filters

Expand Down
6 changes: 3 additions & 3 deletions rules/adblock/blocked-links.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ Checks for links and resources pointing to blocked tracking domains (matched ser
| | |
|---|---|
| **Rule ID** | `adblock/blocked-links` |
| **Category** | [Adblock Detection](/rules/adblock) |
| **Category** | [Blocking](/rules/adblock) → Ad blocking |
| **Scope** | Site-wide |
| **Severity** | info |
| **Severity** | warning |
| **Weight** | 2/10 |

## Solution
Expand Down Expand Up @@ -43,7 +43,7 @@ maxMatchesToReport = 20
disable = ["adblock/blocked-links"]
```

### Disable all Adblock Detection rules
### Disable all Blocking rules

```toml squirrel.toml
[rules]
Expand Down
4 changes: 2 additions & 2 deletions rules/adblock/element-hiding.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Checks for elements that would be hidden by common adblockers (matched server-si
| | |
|---|---|
| **Rule ID** | `adblock/element-hiding` |
| **Category** | [Adblock Detection](/rules/adblock) |
| **Category** | [Blocking](/rules/adblock) → Ad blocking |
| **Scope** | Site-wide |
| **Severity** | warning |
| **Weight** | 3/10 |
Expand Down Expand Up @@ -44,7 +44,7 @@ maxMatchesToReport = 20
disable = ["adblock/element-hiding"]
```

### Disable all Adblock Detection rules
### Disable all Blocking rules

```toml squirrel.toml
[rules]
Expand Down
17 changes: 12 additions & 5 deletions rules/adblock/index.mdx
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
---
title: "Adblock Detection"
description: "Detection of content blocked by ad blockers and privacy filters"
title: "Blocking"
description: "Content, links, and trackers that ad blockers and privacy filters block"
---

<Note>**Cloud rules** - requires login (`squirrel auth login`). All three rules share a single **5-credit** blocklist check per audit, matched server-side against the full EasyList and EasyPrivacy filter lists. Skipped when not logged in. See [Cloud rules](/cloud/rules).</Note>

Detection of content blocked by ad blockers and privacy filters.
The **Blocking** category covers content, links, and trackers that ad blockers and privacy filters would block. It reports in its own report section with two sub-groups - **Ad blocking** and **Privacy blocking** - and every check is a **warning** (it's signal worth knowing, not a hard failure). Enabled by default for logged-in users.

## Rules
<Note>Rule IDs and config filters keep the `adblock/` prefix (e.g. `adblock/*`) - only the report category was renamed to Blocking.</Note>

## Ad blocking

<CardGroup cols={2}>
<Card title="Adblock Element Hiding" icon="triangle-exclamation" href="/rules/adblock/element-hiding">
Expand All @@ -16,12 +18,17 @@ Detection of content blocked by ad blockers and privacy filters.
<Card title="Blocked Tracking Links" icon="circle-info" href="/rules/adblock/blocked-links">
Checks for links and resources pointing to blocked tracking domains
</Card>
</CardGroup>

## Privacy blocking

<CardGroup cols={2}>
<Card title="Privacy Filter Matches" icon="circle-info" href="/rules/adblock/privacy-blocked">
Checks for trackers and analytics that EasyPrivacy would block
</Card>
</CardGroup>

## Disable All Adblock Detection Rules
## Disable all Blocking rules

```toml squirrel.toml
[rules]
Expand Down
6 changes: 3 additions & 3 deletions rules/adblock/privacy-blocked.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ Checks for trackers and analytics that privacy filter lists (EasyPrivacy) would
| | |
|---|---|
| **Rule ID** | `adblock/privacy-blocked` |
| **Category** | [Adblock Detection](/rules/adblock) |
| **Category** | [Blocking](/rules/adblock) → Privacy blocking |
| **Scope** | Site-wide |
| **Severity** | info |
| **Severity** | warning |
| **Weight** | 2/10 |
| **Default** | Enabled |

Expand All @@ -33,7 +33,7 @@ Analytics, session replay, and tracking pixels on matched domains will silently
disable = ["adblock/privacy-blocked"]
```

### Disable all adblock rules
### Disable all Blocking rules

```toml squirrel.toml
[rules]
Expand Down
4 changes: 2 additions & 2 deletions rules/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,8 @@ Most rules run locally for free. A handful of [cloud rules](/cloud/rules) use AI
<Card title="E-E-A-T" icon="folder" href="/rules/eeat">
Experience, expertise, authority, trust signals (15 rules)
</Card>
<Card title="Adblock Detection" icon="folder" href="/rules/adblock">
Detection of content blocked by ad blockers (3 rules)
<Card title="Blocking" icon="folder" href="/rules/adblock">
Content, links, and trackers blocked by ad blockers and privacy filters (3 rules)
</Card>
<Card title="Gap Analysis" icon="folder" href="/rules/gaps">
Keyword and content gaps backed by live search data (2 rules, opt-in)
Expand Down
Loading