Skip to main content
JUMP TO:Quick StartCLI CommandsConfigurationPlaywright APIMCP ServerGitHub Actions
Reference / CLI Commands(5 of 37)

CLI Commands

The supported command surface includes run, init, update-baselines, doctor, guide, monitor, fix-pattern commands, and plugin subcommands.

Commands

CLI Commands and Exit Code Contract
FIG 01 · CLI COMMAND WORKFLOW — INIT · DOCTOR · UPDATE-BASELINES · RUN & EXIT CODES (0 / 1 / 2)
CommandDescriptionCommon Example
frontguard runRender configured routes/viewports and compare against accepted baselines on frontguard-baselines.frontguard run --wait-for-stability --redact-sensitive
frontguard update-baselines --confirm-baselinesCapture 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 doctorDiagnose 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 monitorPoll 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-patternsExport 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
terminal
$ frontguard run --url http://localhost:3000 --threshold 0.01 --wait-for-stability --redact-sensitive --color-scheme dark --freeze-time [timestamp] --seed-random [seed] --block-urls <patterns...>
$ frontguard update-baselines --confirm-baselines --url http://localhost:3000
$ frontguard doctor
$ frontguard guide [topic] --json
$ frontguard monitor --url https://example.com --threshold 0.05
$ frontguard monitor --history

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.

FlagType / ValuesDescription
--url <url>stringOverride 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>numbersOverride viewport widths with one comma-separated list (e.g., --viewports 375,768,1440).
--browsers <list>chromium | firefox | webkitBrowsers to render across.
--color-scheme <scheme>light | darkEmulate 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-stabilitybooleanPoll consecutive animation frames until pixel variance converges (< 0.05%) before capture.
--redact-sensitivebooleanMask password/email/tel inputs and [data-frontguard-redact] elements and scrub DOM snapshots prior to capture.
--freeze-time [timestamp]boolean | number | ISO stringLock 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 | numberInject 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 | jsonEmit human-readable console output or structured JSON to stdout.
--dockerbooleanExecute 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.