Replay
Rebuild the state of a recorded run and stop at the step you want to look at. Replay runs the run's own flow again on your current target, from the start, so your agent can inspect the screen just before or at a failure.
Try it autonom replay --bundle <dir> --to-step 4
Needs a session on one target · a flow run
How it works
A replay starts from a recorded run. --bundle names a finalized report bundle, which autonom report bundle --run ID --out DIR writes; Autonom verifies the bundle first and replays the copy of the flow stored inside it. --run names a run of the current session, or of the session --session names, and replays the flow file from the path the run recorded. With neither, the session's latest run is the source.
The replay itself always runs on the current session's target, so a current session is required even when the source is a bundle. It runs the flow from its first step, with the source run's --env values. Secrets are read again from your environment by name, because the run recorded only their names. Evidence is kept for every step: screenshots, screen trees, logs and requests.
--to-step chooses where to stop. It takes a runtime index such as 4, or a stable step id such as src_4d88cd3b8ce7.1. The replay stops right after that step, with status replayed, once the step ends the way it ended in the source run. A step that failed there must fail again, so you can stop exactly on a failure.
Replay does no cleanup. It does not reset the app or the device before it starts, beyond what the flow's own steps do. When it stops at --to-step, the flow's onFlowComplete steps do not run, so the device stays in that state for your agent to inspect. Each replay is a new run in the session, linked to the source by parent_attempt_id.
The exit code says how the replay ended:
0, statusreplayed: the replay stopped at the--to-stepstep, which ended as it did in the source run. Without--to-step, statuspassed: the whole flow passed.1, statusfailedandtargetnull: a step failed before the replay reached its stop, or the--to-stepstep failed where it had passed in the source run. Without--to-step, the flow failed. Inspect the new run to see which step failed.2, an error object on stderr: the replay was refused before anything ran, or, withflow_replay_step_not_reachedafter the flow ran, the flow finished every step without the--to-stepstep ending as it did in the source run. A failure that no longer happens gives this.
Examples
Every output here comes from Autonom's test emulator showing a PIN screen, so you can rerun it without a device. The source run types a PIN from the APP_PIN secret, taps Continue, then waits for a Welcome screen that never comes, so step 6 fails. Reproduce these outputs, at the end of this section, has the exact commands.
Rebuild the state at a step
Goal: put the device back where step 4 left it, and keep it there.
- Replay the bundle up to step 4.
Step 4 is the checkpoint after the PIN was typed.
autonom replay --bundle bundle --to-step 4
You should see status replayed, and the step it stopped at.
What to look at. strategy: baseline says the state was rebuilt by running the flow from its start. The replay's own report records that it stopped early and skipped cleanup:
Stop on the failing step, by its id
Goal: reproduce a failure and leave the device on it.
- Replay up to the failing step.
The stable id comes from the run's report; Agent report shows where to read it.
autonom replay --bundle bundle --to-step src_4d88cd3b8ce7.1
You should see status replayed, with the step failing the same way it failed in the source run.
What to look at. The exit code is 0: the replay did what you asked, which was to reach the failure. The failure is reproducible on this target, and the device now shows the screen where Welcome never appeared, ready for a UI tree. A step id names the same step even if the flow gains a conditional branch, where an index could point somewhere else.
Replay the whole run
Goal: check whether a failure still happens, from start to end.
- Replay without
--to-step.autonom replay --bundle bundle
You should see status failed and exit code 1, as for a failed flow run.
What to look at. target is null because no stop was requested. After a fix, the same command passing with exit code 0 shows that the failure is gone on this target.
When the replay does not reach its step
Goal: tell a replay that went another way from a failure that no longer happens.
- Replay up to step 4 after the PIN field was renamed.
The script now shows the PIN field with the label
Code, so step 2, which tapsPIN, finds nothing.autonom replay --bundle bundle --to-step 4 - Replay up to the failing step after Welcome appears.
The script now shows Welcome, so step 6 passes where it failed in the source run.
autonom replay --bundle bundle --to-step src_4d88cd3b8ce7.1
You should see status failed with exit code 1 for the first, and flow_replay_step_not_reached with exit code 2 for the second.
What to look at. Both replays ran on the device. Exit code 1 with --to-step means the replay never got to its stop: the state differs from the source run before that step, so read the new run with agent inspect to find the step that failed. Exit code 2 with last_step means the flow ran to its end, and the step you asked for did not fail this time: on this target the failure no longer reproduces.
Read the refusals
Goal: tell why a replay did not start, from the error code alone.
Each refusal below is one error object on stderr, with exit code 2, and nothing runs on the device.
What to look at. flow_replay_step_not_reached before anything ran means the source run has no such step. The help of v0.36.1 also accepts a checkpoint name, but its report records each checkpoint step under the name checkpoint, so pin-entered is not found; pass the checkpoint's index or step id instead. flow_secret_undefined names the variables to export. replay_manifest_invalid means the flow file is gone; a bundle source avoids it, because the bundle keeps its own copy. report_integrity_failed lists each file whose digest no longer matches. no_active_session asks for a session to replay on.
Reproduce these outputs
From the root of an Autonom checkout at tag v0.36.1 (commit ca2a280), in bash or zsh. The autonom function runs that checkout against its test emulator, and the script writes the PIN screen it shows, then two changed copies of it. Run ids, attempt ids, session ids and times differ on every run, and are shortened to … on the page; step ids stay the same, because the flow has an id. On macOS the moved flow's path starts with /private/tmp.
Good to know
Prefer a bundle as the source. It is verified before anything runs and carries its own copy of the flow, so it still replays after the checkout moves on. A
--runsource needs the flow file at the path the run recorded.Prefer step ids to indexes. An index counts runtime steps, so a conditional or a retry can shift it. A step id is derived from the flow's
id, or its path, and the step's line, column and command.The replay checks the outcome, not only the position. A step that passed in the source run must pass again before the replay stops there; if it fails, the replay exits 1. A step that failed must fail again; if it passes and the flow finishes, the replay exits 2 with
flow_replay_step_not_reached.Nothing is cleaned up for you. The app keeps its data from earlier runs unless the flow's own steps reset it, and
onFlowCompletedoes not run after an early stop. Stop the app or the session yourself when you are done looking.Every replay starts from the first step. Autonom v0.36.1 takes no device snapshots: on an emulator or Simulator a checkpoint is restored by replaying the flow up to it, and an Android phone cannot be snapshotted at all. Capabilities shows this as
checkpoint.restore.Secret values are not recorded, but the screen is. The run records only the secret's name, so a replay needs the same variable exported, and the value is not written into the flow, the recorded command line or the steps' arguments. Screenshots, screen trees and logs keep whatever the screen showed: a field that displays the typed value puts it into the run, its bundle and its report. Agent report shows where it ends up.
Reference
autonom replay takes one source and an optional stop.
| Command | What it does |
|---|---|
autonom replay --bundle DIR | Verifies the report bundle, then replays the copy of the flow stored in it. |
autonom replay --run ID | Replays a run of the current session from its recorded flow file. Add --session ID to take the run from another session. |
autonom replay | Replays the current session's latest run. |
--to-step STEP | Stops after the step with this runtime index or stable step id, once it ends as it did in the source run. |
--session ID | The session that holds the --run source. The replay still runs in the current session. |
The error codes, each with exit code 2. A replay that runs and fails before its stop is not one of them: it exits 1 with status failed.
| Error code | When |
|---|---|
flow_replay_step_not_reached | --to-step names no step of the source run, so nothing ran. Or the flow ran every step without that step ending as it did in the source run, for example because a failure no longer happens. |
replay_manifest_invalid | The flow file a --run source points at is gone. |
flow_secret_undefined | A secret the source run used is not set in your environment. |
report_integrity_failed | The bundle has no manifest, or a file in it no longer matches its digest. |
no_active_session | No session is running to replay on. |
Next steps
You can rebuild the state of any recorded run and stop where you need to look.