CLI Commands
The supported command surface includes run, init, update-baselines, doctor, guide, monitor, fix-pattern commands, and plugin subcommands.
Commands
| Command | Description | Common Example |
|---|---|---|
frontguard run | Render configured routes/viewports and compare against accepted baselines on frontguard-baselines. | frontguard run --wait-for-stability --redact-sensitive |
frontguard update-baselines --confirm-baselines | Capture current renders and commit them as accepted baselines on the frontguard-baselines orphan branch. | frontguard update-baselines --confirm-baselines --url http://localhost:3000 |
frontguard init [--ci] [--yes] | Detect framework, generate frontguard.config.ts, and optionally scaffold a comparison-only GitHub Actions workflow. | frontguard init --ci --yes |
frontguard doctor | Diagnose Node.js version, Playwright browser binaries, configuration schema, and git working tree cleanliness. | frontguard doctor |
frontguard guide [topic] [--json] | Print offline developer & coding-agent reference guides (setup, diffing, mcp, playwright, ci). | frontguard guide diffing --json |
frontguard monitor | Poll or run a one-shot visual check against a live production/staging URL and record history under .frontguard/monitor-history. | frontguard monitor --url https://example.com --threshold 0.05 --once |
frontguard accept-fix <id> | Record a candidate CSS fix as accepted in the local .frontguard/fix-patterns.json database. | frontguard accept-fix 1 |
frontguard reject-fix <id> | Record a candidate CSS fix as rejected (negative signal in .frontguard/fix-patterns.json). | frontguard reject-fix 1 |
frontguard export-patterns | Export the local fix-pattern database as JSON for sharing across repositories. | frontguard export-patterns > patterns.json |
frontguard plugin <subcmd> | Install, uninstall, or list Frontguard lifecycle plugins (install, uninstall, list). | frontguard plugin list |
Run flags reference
Use frontguard guide [topic] (topics: setup, diffing, mcp, playwright, ci) with --json for offline CLI and coding-agent reference output. Capture and anti-flake flags include --wait-for-stability for multi-frame render convergence, --redact-sensitive to mask sensitive inputs and scrub DOM snapshots before capture, --color-scheme <scheme> (light or dark) to emulate prefers-color-scheme, --freeze-time [timestamp] (epoch ms or ISO 8601 date string), --seed-random [seed] for deterministic Math.random() seeding, and --block-urls <patterns...> to abort third-party analytics or ad requests.
| Flag | Type / Values | Description |
|---|---|---|
--url <url> | string | Override baseUrl from frontguard.config.ts (useful for staging or preview URLs). |
--threshold <ratio> | number (0-1) | Maximum allowed changed-pixel ratio (e.g., 0.01 = 1%). |
--viewports <list> | numbers | Override viewport widths with one comma-separated list (e.g., --viewports 375,768,1440). |
--browsers <list> | chromium | firefox | webkit | Browsers to render across. |
--color-scheme <scheme> | light | dark | Emulate prefers-color-scheme before rendering. Compares against the same baseline file as the default scheme until named capture modes exist, and warns when the stored scheme differs. The warning does not change the exit code. |
--wait-for-stability | boolean | Poll consecutive animation frames until pixel variance converges (< 0.05%) before capture. |
--redact-sensitive | boolean | Mask password/email/tel inputs and [data-frontguard-redact] elements and scrub DOM snapshots prior to capture. |
--freeze-time [timestamp] | boolean | number | ISO string | Lock page.clock and Date.now() to a fixed epoch ms or ISO 8601 timestamp (e.g., 2026-01-01T00:00:00Z). |
--seed-random [seed] | boolean | number | Inject a deterministic Mulberry32 PRNG overriding Math.random() (default seed: 42). |
--block-urls <patterns...> | string[] | Abort matching third-party network requests (ads, analytics, live chat widgets) during page load. |
--output <format> | console | json | Emit human-readable console output or structured JSON to stdout. |
--docker | boolean | Execute rendering inside the local frontguard/render Docker container. |
Threshold units
Changed-pixel ratio (0-1; 0.01 = 1%). Legacy values over 1 are deprecated. The monitor alert threshold uses the same ratio convention: 0.05 = 5%.
Exit codes
- 0: comparisons passed or produced warnings only.
- 1: regressions or unaccepted new screenshots.
- 2: no comparisons or any tool error; errors take precedence over regressions.
Monitoring
The local monitor command records run history under .frontguard/monitor-history by default. Webhook delivery is best-effort; no managed cloud scheduler is generally available.
