Preview uploads & sharing

peach test --preview, peach record --mode combined, and peach record upload publish the app running in your sim to a /preview/<id> link. Whoever opens it watches the recorded flow, then taps in and uses your real app live. They need no install, no TestFlight, no dev build, and no Xcode.

Use it to:

  • +
    attach a playable demo to every pull request
  • +
    hand a designer, PM or client a link to the real app
  • +
    share a bug repro, sales demo or onboarding walkthrough that anyone can replay

Who can open a preview

  • +
    Previews tied to a GitHub repository start unlisted. Anyone with the URL can open the app and its recording without signing in, even when the repository is private. This covers previews from the Peach GitHub App and uploads you associate with a repository using --owner <org> --repo <repo>. Repository privacy does not make the link private.
  • +
    Every other upload starts private. Only signed-in members of your account can open it.

The preview page’s share menu shows Public link, on for unlisted previews. An authorized owner can turn it on to share a private preview, or off to require account or repository access. Uploading the same preview again keeps an explicit choice.

Record a flow and share it

terminal
peach login # first time only
peach test .maestro/login.yaml --preview

--preview records the run, captures its event stream, uploads both, and prints the /preview/<id> link. Add --preview-open to open it in your browser.

Record the sim and share it

terminal
peach record --mode combined --duration 8 --open

combined captures the scene and event stream, renders video after stop, and uploads them. --open opens the link when the upload finishes. To record a longer session across several commands, start and stop it yourself:

terminal
peach record start --mode combined
# drive the app
peach record stop

The preview id comes from your app’s bundle. Recording the same app again reuses the link and replaces the previous recording. Copy a recording you want to keep somewhere else before you record that app again.

Upload an existing recording

terminal
peach record upload --video ./demo.mp4 --open
peach record upload --video ./demo.mp4 --events ./demo-events.jsonl.gz --open

Attach an MP4 or GIF recording, a gzipped event stream, or both, from an earlier run or a scripted harness. Keep the app open in Peach while you upload, because the upload captures its bundle from the sim. To publish a bundle with no recording at all, use peach preview.

Sign-in

Uploads need a signed-in session or a PEACH_API_KEY with the preview_upload scope.

terminal
peach login # sign in
peach auth # show which credential is active
peach logout # clear the local session

Uploads go to https://peachsim.com by default. Override the host with --origin <url> or the PEACH_UPLOAD_ORIGIN environment variable.

What the preview page does

  • +
    Live app: your real bundle runs in the visitor’s browser, on their GPU, through WebAssembly. Nothing is streamed from a server.
  • +
    Recording: the recorded flow plays over the app. Drag the scrubber to jump to any point in it.
  • +
    Take control: tap the app to leave playback and drive it live from where the recording left it.

Pull request previews

For the managed Peach GitHub App, the repository runs a generated workflow and stores no PEACH_API_KEY. Each pull request gets one sticky comment with thumbnails and a /preview/<id> link, which reviewers open to watch the recording and then use the live app. A failed preview capture fails the workflow. The separate Peach Tests check reports test results.

To wire your own CI instead, run the flow, capture video and events, and call peach record upload --video ... --events ... with an API key.

Flags you’ll want to know

commandflageffect
peach test--previewrecord and upload in one step
peach test--preview-openopen the link after a successful run
peach record--mode combinedcapture video and events, then upload
peach record--owner <org> --repo <repo>tie the preview to a linked repository
peach record upload--video <path>attach an MP4 or GIF recording
peach record upload--events <path>attach a gzipped .jsonl.gz event stream
peach record upload--sim <sim>upload from a specific sim
peach record upload--openopen the link after upload
peach record upload--origin <url>upload to another host