URL: /cli/audit

---
title: "audit"
description: "Run an audit on a website"
---

The `audit` command crawls a website and runs SEO rules to generate a report.

## Usage

```bash
squirrel audit <url> [options]
```

## Arguments

| Argument | Description |
|----------|-------------|
| `url` | The URL to audit (required) |

## Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--max-pages` | `-m` | Maximum pages to crawl | varies by coverage mode |
| `--coverage` | `-C` | Coverage mode: `quick`, `surface`, `full` | `surface` |
| `--format` | `-f` | Output format: `console`, `text`, `json`, `html`, `markdown`, `xml`, `llm` | `console` |
| `--output` | `-o` | Output file path | auto |
| `--refresh` | `-r` | Ignore cache, fetch all pages fresh | `false` |
| `--resume` | | Resume interrupted crawl for this domain | `false` |
| `--verbose` | `-v` | Verbose output | `false` |
| `--debug` | | Enable debug logging | `false` |
| `--trace` | | Enable performance tracing | `false` |
| `--project-name` | `-n` | Project name (overrides config and prompts) | auto |
| `--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` |
| `--offline` | | Run fully offline: skip cloud features, publishing, and telemetry | `false` |

### Coverage Modes

| Mode | Default Pages | Description |
|------|---------------|-------------|
| `quick` | 25 | Fast scan - seed URL + sitemaps only, no link discovery |
| `surface` | 100 | Smart sampling - one page per URL pattern (default) |
| `full` | 500 | Comprehensive - crawl everything up to limit |

<Note>
For SARIF format (IDE integration), use the `report` command after running an audit:
```bash
squirrel audit https://example.com
squirrel report <audit-id> --format sarif
```
See the [report command docs](/cli/report) for details.
</Note>

## Examples

### Basic Audit

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

### Quick Health Check

```bash
squirrel audit https://example.com -C quick
```

### Full Comprehensive Audit

```bash
squirrel audit https://example.com -C full
```

### Crawl More Pages

```bash
squirrel audit https://example.com -m 200
```

### Export to JSON

```bash
squirrel audit https://example.com -f json -o report.json
```

### Generate HTML Report

```bash
squirrel audit https://example.com -f html -o report.html
```

### Fresh Crawl (Ignore Cache)

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

### Audit and Publish

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

Publish with unlisted visibility:

```bash
squirrel audit https://example.com --publish --visibility unlisted
```

<Note>
Publishing requires authentication. Run `squirrel auth login` first.
</Note>

### Fully Offline Audit

Run an audit with zero network calls beyond the site being audited — no cloud
analysis, no publishing, no update checks, no telemetry. Results are stored in
the local database as usual:

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

`--offline` cannot be combined with `--publish` or `--render` (both require
cloud access and login).

### Verbose Output

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

## Output Formats

### Console (default)

Human-readable output with colored issue severity:

```
squirrelscan v0.1.0
========================================
Auditing  https://example.com
Coverage  surface · max 100 pages
Config    defaults
Account   you@example.com · 500 credits
Dashboard https://app.squirrelscan.com

Crawled 12 pages

ISSUES

[high] Missing meta description
  → /about
  → /contact

[medium] Image missing alt text
  → /images/hero.png on /

[low] Non-HTTPS link
  → http://oldsite.com on /links
```

### JSON

Machine-readable JSON for CI/CD pipelines and AI processing:

```bash
squirrel audit https://example.com -f json -o report.json
```

```json
{
  "url": "https://example.com",
  "crawledAt": "2025-01-08T00:00:00Z",
  "pages": [...],
  "issues": [...],
  "stats": {
    "totalPages": 12,
    "issueCount": { "high": 2, "medium": 3, "low": 5 }
  }
}
```

### HTML

Visual report you can open in a browser:

```bash
squirrel audit https://example.com -f html -o report.html
open report.html
```

## Crawl Behavior

The audit command manages crawl sessions intelligently:

| Scenario | Behavior |
|----------|----------|
| First run | Creates new crawl |
| Re-run (completed) | New crawl, uses cache for 304s |
| Re-run (interrupted) | Resumes from where it left off |
| Config changed | New crawl with fresh scope |

<Info>
Changing scope-affecting config (`include`, `exclude`, `allow_query_params`, `drop_query_prefixes`) triggers a fresh crawl.
</Info>

## Caching

SquirrelScan caches page content locally. On subsequent audits:

- **304 Not Modified**: Uses cached content (fast)
- **200 OK**: Fetches fresh content (slower)

Use `--refresh` to bypass the cache entirely.

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Error (invalid URL, crawl failed, etc.) |

## Configuration

The audit command respects settings from `squirrel.toml`:

```toml
[crawler]
max_pages = 100
delay_ms = 200
timeout_ms = 30000
include = ["/blog/*"]
exclude = ["/admin/*"]

[rules]
enable = ["*"]
disable = ["ai/*"]
```

See [Configuration](/configuration) for all options.

## Using with AI

Pipe JSON output to your LLM:

```bash
squirrel audit https://example.com -f json | claude "analyze this SEO report"
```

Or use with Claude Code's MCP integration for interactive auditing.

## Related

- [Crawling](/crawl) - How the crawler works
- [Configuration](/configuration) - Config file options
- [squirrel report](/cli/report) - View stored audit reports