CLI Commands
Complete reference for all Frontguard CLI commands, flags, and options.
CLI Commands
Frontguard provides three commands: run, init, and update-baselines.
frontguard run
The default command. Runs the visual regression testing pipeline.
frontguard run [options]Options
| Flag | Description | Default |
|---|---|---|
-u, --url <url> | Base URL to test | From config |
-r, --routes <routes> | Comma-separated routes to test | Auto-discovered |
-v, --viewports <widths> | Comma-separated viewport widths | 375,768,1440 |
-b, --browsers <engines> | Comma-separated browsers | chromium |
-c, --config <path> | Path to config file | Auto-detected |
-o, --output <format> | Output format: console, json | console |
-t, --threshold <n> | Pixel diff threshold percentage (0-100) | 0.1 |
--verbose | Verbose output | false |
--debug | Debug output with Playwright traces | false |
--update-baselines | Accept current screenshots as baselines | false |
Examples
frontguard run --url http://localhost:3000frontguard run --url http://localhost:3000 --routes /,/pricing,/checkoutfrontguard run --url http://localhost:3000 --browsers chromium,firefox,webkitfrontguard run --url http://localhost:3000 --viewports 320,768,1920frontguard run --url http://localhost:3000 --output jsonfrontguard run --url http://localhost:3000 --threshold 0.01The threshold value works as a percentage. Values over 1 are automatically converted: --threshold 5 becomes 0.05 (5%).
Exit Codes
| Code | Meaning |
|---|---|
0 | All tests passed (or only warnings/new pages) |
1 | Regressions detected |
2 | Pipeline errors (but no regressions) |
frontguard init
Generates a starter frontguard.config.ts file. Auto-detects your framework and creates sensible defaults.
frontguard initThis 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-baselinesThis command:
- Renders all routes at all configured viewports
- Saves the screenshots as the new baseline set
- Updates the baseline manifest
This overwrites existing baselines. Make sure the current state of your app is correct before running this command.
Global Options
These options work with all commands:
| Flag | Description |
|---|---|
--version | Print Frontguard version |
--help | Show help for a command |
frontguard --version
frontguard run --helpEnvironment Variables
| Variable | Description |
|---|---|
FRONTGUARD_OPENAI_KEY | OpenAI API key for AI analysis |
FRONTGUARD_ANTHROPIC_KEY | Anthropic API key for AI analysis |
GITHUB_TOKEN | GitHub token for PR comments |
FRONTGUARD_DEBUG | Set to 1 for full stack traces on errors |
FRONTGUARD_UPDATE | Set to 1 to force baseline updates (used by Playwright plugin) |
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.