CLI reference

ShotSweep’s CLI lets you capture screenshots, reuse authenticated sessions, and compare capture runs for visual regressions. The reference below lists every command, flag, and default value, with examples for common workflows.

shotsweep
│
├── capture
├── login
└── diff

shotsweep capture

Take screenshots of one or more pages.

Input (pick one)

URLs don’t need a scheme: example.com becomes https://example.com (http:// for localhost and loopback addresses), and a pasted Markdown link such as [x](https://x.com) is unwrapped. See Inputs & Sitemaps.

Capture behavior

Auth

Reliability & recovery

Output & scripting

shotsweep login

Drive a login form once and save the session for reuse with capture --session.

shotsweep diff

Compare two capture runs using their manifest.json files.

shotsweep diff <old-manifest> <new-manifest>

See Diffing Two Runs for thresholds, regression policy, reports, and exit-code behavior.

Config file

Drop a shotsweep.config.json or .shotsweeprc.json in your project so shotsweep capture and shotsweep diff run with fewer flags.

{
  "sitemap": "https://example.com/sitemap.xml",
  "viewport": ["1440x900", "390x844"],
  "mode": "full",
  "out": "./screenshots",
  "diff": {
    "out": "./diff",
    "threshold": "loose",
    "summary": true,
    "text": "./reports/visual-summary.txt"
  }
}

Top-level keys are shared defaults for both commands. Repeatable options such as viewport accept either a single string or an array.

A config file that exists but isn’t valid JSON stops the run with an error naming the file, so a typo never silently turns into default settings. Keys that don’t match any option are reported as warnings (on stderr) and ignored.

A "diff" sub-object overrides shared keys specifically for shotsweep diff.

Priority, highest to lowest:

explicit CLI flag → command-specific config (diff.*) → shared top-level config

For example, the config can provide the default threshold, output directory, summary, and text report without requiring those flags every time.

An explicit CLI flag still wins:

shotsweep diff \
  before/manifest.json \
  after/manifest.json \
  --threshold strict

Threshold values from a config file go through the same ratio, percentage, and preset normalization as CLI values.

See Diffing Two Runs.