replay

replay validates a complete recorded sequence. It is read-only by default and emits OS input only when --execute is explicit.

ferrisgrid replay .ferrisgrid/sessions/onboarding-demo

The source may be either a session directory or a direct path to sequences/sequence.md.

Preflight and execution

Before the first live action, FerrisGrid parses every step, enforces the action-count limit, rejects redacted or omitted typed content, maps every recorded screen, validates coordinates and selected-backend input capabilities, and applies the normal action policy. A failure leaves the desktop untouched.

ferrisgrid replay .ferrisgrid/sessions/onboarding-demo --execute

Live replay uses a fixed 300 ms delay by default and writes a new replay session. It never adds files to or changes the source recording. Checkpoint screenshots are taken after the corresponding actions.

Clipboard paste hotkeys may be valid but depend on external clipboard state. Dry-run and live output report how many such warnings were found; FerrisGrid does not restore or inject the recorded clipboard contents.

Screen mapping

FerrisGrid first matches a recorded display fingerprint, then the recorded screen ID. If the layout changed, map the old ID to a current ID explicitly:

ferrisgrid replay sequences/sequence.md \
  --map-screen screen-2=screen-1

Repeat --map-screen for multiple displays. Run ferrisgrid doctor or ferrisgrid observe to inspect current IDs.

Options

Option	Purpose
--execute	Emit OS input after successful whole-sequence preflight.
--delay-ms <0..30000>	Fixed delay between actions. Defaults to 300.
--max-actions <1..1000>	Guarded action limit. Defaults to 25.
--map-screen <recorded=current>	Map a recorded display to a current screen. Repeatable.
--output-dir <path>	Root for a new live replay session. Defaults to .ferrisgrid.
--session <name-or-path>	Name the new live replay session; existing sessions are never overwritten.
--backend <name>	Select current capture/input backends.
`--format jpg	png`
`--grid-overlay true	false`
`--resolution fast	balanced
--max-image-edge <px>	Set an exact longest-edge cap.
--no-downsample	Keep native screenshot dimensions.

Treat --execute as a privileged operation: focus the intended application, verify the dry-run result, and be ready to interrupt the process.