CLI & Headless

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

Commands

The CLI shape is:

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

• run: takes new snapshots and then analyzes
• re-analyze: analyzes existing snapshots without taking new ones

Options

• --scene <name>: run only a specific scene by name
• --all: report all results instead of only the latest relevant result
• --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

CI recommendations

• Use --format json and parse summary status/counts in pipeline steps
• 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
• A scene can be marked failed when visual diffs exceed threshold

Use Integration Guide for scene architecture and launch argument strategy.