CLI Commands

Frontguard provides: run, init, update-baselines, doctor, monitor, the fix-pattern commands (accept-fix, reject-fix, export-patterns), and the plugin subcommands (install, uninstall, list).

frontguard run

The default command. Runs the visual regression testing pipeline.

frontguard run [options]

Options

To accept current screenshots as new baselines, use the dedicated frontguard update-baselines command rather than a flag on run.

Examples

frontguard run --url http://localhost:3000

frontguard run --url http://localhost:3000 --routes /,/pricing,/checkout

frontguard run --url http://localhost:3000 --browsers chromium,firefox,webkit

frontguard run --url http://localhost:3000 --viewports 320,768,1920

frontguard run --url http://localhost:3000 --output json

frontguard run --url http://localhost:3000 --threshold 0.01

Exit Codes

frontguard init

Generates a starter frontguard.config.ts file. Auto-detects your framework and creates sensible defaults.

frontguard init

This creates a config file in your project root with:

• Framework-appropriate settings (Next.js, Remix, SvelteKit, Nuxt, Astro)
• Default viewports (mobile, tablet, desktop)
• Route discovery configuration
• Common ignore rules for dynamic content

frontguard update-baselines

Accepts the current screenshots as the new baselines. Run this after intentional visual changes.

frontguard update-baselines

This command:

1. Renders all routes at all configured viewports
2. Saves the screenshots as the new baseline set
3. Updates the baseline manifest

frontguard doctor

Diagnoses your environment for sources of non-determinism before you run tests — the table-stakes "is everything set up right?" check.

frontguard doctor

It checks Node and Playwright/Chromium versions, browser availability, config validity, and git state, printing actionable warnings for anything that could cause flaky diffs (missing browser binaries, an invalid config, etc.). Exit code 0 means the environment is ready.

frontguard monitor

Runs visual checks against live production URLs instead of a local dev server — the CLI side of production monitoring. See the Production Monitoring guide for the full workflow.

frontguard monitor --url https://example.com,https://example.com/pricing

Options

frontguard monitor --url https://example.com --threshold 2

frontguard monitor --url https://example.com --interval 15 --webhook $SLACK_WEBHOOK

frontguard monitor --history --limit 50

Fix-pattern commands

Frontguard learns from the AI fixes you accept or reject. See the AI Fixes guide for the full loop.

Plugin commands

Global Options

These options work with all commands:

frontguard --version
frontguard run --help

Environment Variables

Output Formats

Console (default)

Human-readable output with color-coded statuses, ASCII tables, and AI analysis summaries.

JSON

Machine-readable JSON output for CI/CD integration. The JSON structure follows the RunResult type:

{
  "summary": {
    "total": 36,
    "passed": 33,
    "regressions": 1,
    "warnings": 1,
    "newPages": 1,
    "errors": 0
  },
  "diffs": [...],
  "timing": {
    "discovery": 1200,
    "render": 8500,
    "compare": 300,
    "ai": 2100,
    "total": 12100
  }
}

HTML Report

An HTML report is automatically generated in the outputDir (default: ./frontguard-report/) regardless of the output format. It includes side-by-side screenshot comparisons, diff overlays, and AI analysis details.