CLI and output
Capture commands, saved files, warnings, and result fields.
Invocation
With the source checkout installed, run from that checkout:
pnpm capture --project-root /absolute/path/to/app \
--config snapbot.json --output snapbot-output/run-001
pnpm exec tsx src/main.ts --helpThe executable's capture command is snapbot capture. The pnpm capture
script already supplies capture; do not repeat the word. help, --help,
or no command print usage. The current parser does not implement capture --help, --version, --dry-run, or a JSON output flag.
| Flag | Meaning |
|---|---|
--config | Required JSON config path. |
--output | Required new or empty output directory. |
--project-root | Root for relative paths; defaults to the current working directory. |
--dotenv | Load environment values before reading configuration; existing values win. |
--exec | Run an executable after a finalized capture; see automation. |
Use space-separated flag values as in the examples. The runtime parser in
src/main.ts
is the authority for supported flags.
Output and exit status
The current CLI prints captured PNG paths to stdout and diagnostics to stderr.
It does not emit the standard twocents JSON envelope. Automated consumers
should use the exit status and summary.json; do not parse stdout as JSON.
The summary currently has no protocolVersion, requestID, or structured
retry-safety classification. Do not assume those fields exist.
- Exit
0: capture success, including visual-stability or repeated-frame warnings. - Exit
1: argument/configuration errors, capture failures, or a failed post-run executable.
A nonempty output directory is rejected without deleting its contents. A lock prevents two captures from using the same directory at once. Choose a fresh directory for each run; Snapbot does not choose names, retention rules, or overwrite policy.
The output contains captured PNGs, run.log, and summary.json. Failure paths
may retain a failure screenshot and intermediate diagnostics. Summaries are
written atomically, initially with status: "running", then finalized. A hard
process interruption can leave a running summary or lock; inspect the process
and artifacts before manual cleanup. Configuration errors and failures to
reserve the output directory occur before a summary is created.
Summary structure
The authoritative types are RunSummary in
src/main.ts and
AppCaptureResult, ScreenshotResult, and StabilityResult in
src/ios.ts and
src/lib.ts.
| Location | Contents |
|---|---|
| Root | status, command (capture), absolute outputDirectory, startedAt; finalized runs add finishedAt. app and error are conditional. |
app | App name, status, screenshots; optional config path, environment, appearance, timestamps, simulator, warning, error, and failure screenshot. |
app.simulator | Name, UDID, runtime, and device type. |
app.screenshots[] | Expanded name, original configuredName, deep link, state array, optional flag, absolute PNG path, environment, appearance, authentication, setup, and nullable navigation error. |
| Screenshot stability | stable, timedOut, samples, pixelHash, width, and height. |
setup | The same stability fields, for the setup screen preceding that screenshot. |
authentication | attempted, nullable succeeded, and optional reused, stable, and timedOut. |
failureScreenshot | When available, a path, width, height, and pixel hash for the failure frame. |
Times are ISO 8601 strings. Do not assume optional fields exist on early failures.
Authentication metadata describes the setup attempt/reuse logic; it is not a
confirmation from your identity provider. In particular, succeeded
can remain null for attempted setup even after visual stability.
How Snapbot checks stability
Consecutive decoded frames may differ by up to 0.05% of pixels and still
count as matching. This tolerates a blinking cursor while larger animations
keep the screen unsettled. pixelHash is exact, so two accepted stable frames
can still have different hashes.
On timeout, Snapbot saves the final frame, sets timedOut: true and
stable: false, and continues. Setup timeouts also warn. optional does not
change that policy. Identical consecutive captures from different configured
screens can trigger a warning about stuck navigation or an overlay.
Deep-link navigation errors fail the run even when a visible frame is saved. Build, process, and screenshot-writing failures also fail. A post-run executable failure makes the command exit nonzero while leaving the capture status in the summary unchanged.
A static login error, red error screen, or wrong route can look stable. Review warnings and PNGs, and add your own acceptance policy in the post-run consumer when your workflow needs stricter checks.