CLI & Headless

Watchlight supports headless commands for CI/CD and scripted validation.

Commands

The CLI shape is:

watchlight run [--scene <name>] [--all] [--strict] [--format text|json] <project_path>
watchlight re-analyze [--scene <name>] [--all] [--strict] [--format text|json] <project_path>
watchlight mcp

• run: takes new snapshots and then analyzes
• re-analyze: analyzes existing snapshots without taking new ones
• mcp: starts a stdio MCP server for AI assistant integration (see MCP Server)

MCP mode

watchlight mcp runs a long-lived MCP server over stdin/stdout. Your editor or AI tool starts this automatically when configured — see MCP Server for setup instructions.

The server exposes the same run and re_analyze actions as the CLI, plus agent-focused tools to inspect projects, create/update scenes, validate launch hooks, manage baselines, and fetch artifacts.

Options

• --scene <name>: run only a specific scene by name
• --all: report all results instead of only the latest relevant result
• --strict: return a non-zero exit code when visual diffs fail, not just when execution errors occur
• --format text|json:
  • text: human-friendly output
  • json: structured output for CI/CD

Examples

Analyze all scenes and emit JSON for CI:

watchlight run --format json ./my-project.watchlight.json

Analyze only one scene:

watchlight run --scene "Main Menu" ./my-project.watchlight.json

Re-analyze without new snapshots:

watchlight re-analyze --all ./my-project.watchlight.json

Fail CI immediately when visual diffs exceed threshold:

watchlight re-analyze --strict --format json ./my-project.watchlight.json

CI recommendations

• Use --format json and parse summary status/counts in pipeline steps
• Prefer --strict when CI should fail on visual mismatches
• Persist project file + snapshots as CI artifacts on failures
• Run with deterministic app arguments to reduce flaky diffs
• Keep scene names stable; --scene matching is name-based

Exit behavior

• Successful runs exit 0
• Errors during scene processing return a non-zero exit
• Visual diffs can exceed threshold while still exiting 0 by default
• Use --strict to treat visual failures as process failures

Baseline behavior

Watchlight analyzes each non-baseline snapshot against the scene's effective baseline:

• if a scene has an explicit baseline snapshot, that file is the comparison source
• otherwise the first snapshot by name order is treated as the baseline

Use Integration Guide for scene architecture and launch argument strategy.