Reshot CLI for Product Journeys

The Reshot CLI for Product Journeys gives developers a repository-native path for setup, browser execution, canonical Journey authoring, native Playwright import, evidence upload, Review, publication, export, and diagnosis.

The npm package remains @reshotdev/screenshot for compatibility, while its current product definition is Product Journey Infrastructure.

Install and authenticate

npm install -g @reshotdev/screenshot
reshot auth

Connected canonical commands require a project ID and browser-issued API key. The client sends Bearer authentication. Mutations require a bounded Idempotency-Key, an If-Match revision, channel identity, and request ID.

Keep API keys and Playwright storage state out of source control.

Two command families

The established reshot setup, reshot run, reshot record, reshot evidence, reshot barriers, reshot status, and doctor commands support capture and evidence workflows.

The canonical reshot journey family supports the versioned Product Journey path:

init       initialize repository-scoped authoring
discover   discover native Playwright repositories
import     import native Playwright through the canonical HTTP service
create     create a canonical Journey
edit       create a draft from a JSON document
record     upload real source bytes and attach an Observation
validate   validate the canonical authoring contract
run        execute preserved Playwright and persist the Run
review     record an attributable Decision
publish    publish an exact Journey Version
export     explicit offline TypeScript/JSON/YAML export
doctor     diagnose validity and source preservation

No flag approves a Journey on the user’s behalf.

Create a Journey

reshot journey create \
  --id journey-invite-member \
  --name "Invite a member" \
  --start-url https://preview.example.test/settings/members \
  --checkpoint "The intended recipient is pending" \
  --operation onboarding-invite-v1

The operation key makes a retried mutation deterministic. Server revision protects against hidden concurrent overwrite.

Import Playwright

reshot journey discover
reshot journey import playwright.config.ts \
  --id journey-invite-member \
  --name "Invite a member" \
  --start-url https://preview.example.test/settings/members \
  --checkpoint "Invitation reaches pending state" \
  --operation import-invite-v1

The importer preserves native config, suites, fixtures, authentication references, hashes, and unsupported constructs. It creates protected advanced-code references instead of rewriting source.

Run natively

reshot journey run journey-invite-member \
  --config playwright.config.ts \
  --version journey-invite-member-v1 \
  --mode ci \
  --operation run-invite-ci-184

The CLI creates the canonical Run, executes Playwright in the repository, and completes the Run with success or failure. Native execution is authoritative.

Record evidence

reshot journey record journey-invite-member \
  --run run_184 \
  --version journey-invite-member-v1 \
  --artifact .reshot/output/invite.png \
  --media-type image/png \
  --kind source-visual \
  --operation observation-invite-184

The CLI hashes real bytes, initializes a private presigned upload, uploads directly, commits completion, and attaches an Observation with a caller-attested redaction manifest. The caller remains responsible for redacting before disk.

Review and publish

Review requires a Review Item, outcome, rationale, authority, expected revision, and operation key. Publication requires the exact Journey Version and current revision. A passing Run does not automatically approve or publish.

Export

reshot journey export journey-invite-member --format yaml --offline

Offline export intentionally uses the local authoring cache. TypeScript, JSON, and YAML share canonical semantics.

Storage

Setup can use hosted platform storage or configured S3-compatible storage including Cloudflare R2. Direct uploads use bounded presigned URLs. Production publication requires verified durable storage and receipts.

Exit codes and automation

Commands emit structured JSON for canonical results and write diagnostic errors to stderr with nonzero exit status. CI should fail on validation, native execution, upload, revision, or publication failure rather than parsing a reassuring log line.

Pin the CLI version in release workflows. The package is beta and minor releases may change APIs. Run doctor after upgrades and keep browser/runtime versions aligned with the repository.

Customer-local runner

The reshot runner family supports authenticated customer-local execution where product state or network policy cannot leave the customer environment. The runner still produces bounded signed or content-addressed evidence and does not make local success an automatic Review Decision.

Diagnosis

reshot doctor target checks target readiness and authentication contracts. reshot doctor release checks preflight, targets, and documentation assets. reshot journey doctor checks canonical validity and native-source preservation.

Fix the reported cause rather than suppressing a release gate.

Safety

Use a production-like local server instead of development mode for launch-grade evidence. Authorize destructive side effects explicitly. Keep source secrets, storage state, tokens, and private artifacts out of logs and public exports. Use idempotent operations for every retriable mutation.

Continue with the Playwright integration, Product Journey YAML Reference, and Product Journey API.