JSON output

Use --json when ShotSweep is being consumed by another program, CI pipeline, script, or automation system instead of the default terminal output.

Capture

shotsweep capture --url https://example.com --json

{
  "ok": 1,
  "failed": 0,
  "warnings": 0,
  "total": 1,
  "durationMs": 2417,
  "avgMs": 2417,
  "manifestPath": "screenshots/manifest.json",
  "zipPath": null,
  "recordPath": "screenshots/run-record.json",
  "failures": []
}

failures lists each failed page as { "url", "viewport", "error" }, so a script can report why without opening the manifest. warnings counts pages captured with a caveat (see Troubleshooting); it doesn’t affect the exit code.

If the run can’t start at all (an invalid URL, an unreadable config file), --json prints a single { "error": "..." } line and exits non-zero.

Diff

diff supports the same machine-readable mode:

shotsweep diff old/manifest.json new/manifest.json --json

Example:

{
  "summary": {
    "changed": 2,
    "unchanged": 9,
    "added": 1,
    "removed": 0,
    "sizeChanged": 0,
    "errors": 0,
    "regressions": 2
  },
  "reportPath": "diff/diff-report.json",
  "zipPath": null,
  "environment": { "comparable": true, "drift": [] },
  "decision": { "verdict": "fail", "regressions": 2, "environmentDriftDetected": false }
}

The regressions value represents the number of results that currently count as regressions.

By default:

regressions = changed + sizeChanged + errors

added and removed are reported separately and do not contribute to the regression count. errors counts pages whose screenshots couldn’t be compared.

Text output for humans

If the output is intended for people rather than programs, use --summary:

shotsweep diff old/manifest.json new/manifest.json --summary

You can also save the human-readable summary:

shotsweep diff \
  old/manifest.json \
  new/manifest.json \
  --text ./reports/visual-summary.txt

The text output is intentionally simple so it can be read in terminal logs, CI artifacts, or by humans reviewing a build.

Using both

A CI job can produce machine-readable and human-readable output at the same time:

shotsweep diff \
  old/manifest.json \
  new/manifest.json \
  --json \
  --text ./reports/visual-summary.txt

Use:

• JSON for scripts, CI, bots, and AI tooling.
• TXT for humans, logs, and downloadable artifacts.
• diff-report.json for detailed per-page comparison data.
• old.png, new.png, and diff.png for visual investigation.

With --json, ShotSweep suppresses the spinner and prints exactly one JSON line, making the output safe to pipe into tools such as jq or parse directly in a script.