opschain runs retry
Included from Basic tier
opschain runs retry <run-id> [--skip-step <path>]... [--refresh-git-rev] [--follow]
Retries a run as a NEW duplicate run, in the lane the target selects —
exactly like runs create:
- Locally the duplicate executes attached in the repository: live step
tree, streamed logs, terminal wait prompts, and the process exit code is
the duplicate's outcome.
--followchanges nothing locally — attached is the only local mode. - Against a server the retry is posted on the API v2 retry verb
(
ChangeService.RetryChange, falling through toWorkflowRunService.RetryWorkflowRunfor a non-change id), the new run is printed, and the command returns without waiting.--followopts into polling the duplicate to its terminal status, printing each transition and mapping the terminal status onto the attached-run exit codes. The server must serve/api/v2(every current release does).
Flags
| Flag | Meaning |
|---|---|
--skip-step <path> | Step path or glob to skip in the duplicate (repeatable; an entry skips its whole subtree). On a server this REPLACES the retried run's skip mask. Only sent when the flag is given. --skip-steps <a,b> survives as a deprecated comma-separated alias. |
--refresh-git-rev | Server only: re-resolve the original change's git_rev (branch/tag) to its current target and pin the duplicate to that commit — a sha rev re-resolves to itself. Project/environment git changes only: an asset change's commit comes from its template version, so the server refuses the option with its named error (surfaced verbatim), and a workflow-run id is refused by the CLI before the fall-through. |
--follow | Server: poll the duplicate until it finishes, printing status transitions. A local retry is always attached. |
--approve-all | Local only: auto-answer wait and approval steps with their defaults. Refused by name on a server target — a server run's waiting steps are answered with runs approve, runs continue and runs reject. |
--follow-logs <step-path> | Local only: show log output for this step path (and its descendants) only. Refused by name on a server target. |
-o json|yaml prints the created run (or, locally / with --follow, the
finished result) as a machine document; -q, --quiet prints only the new
run's id.
Output
Against a server (without --follow):
created change 0199c8f1-… (deploy on demo/dev) — pending
Locally (or with --follow, as status transitions):
run 0199c8f1-… success (2m04s)
Exit codes
| Code | Meaning |
|---|---|
| 0 | The duplicate was created (server without --follow), or succeeded. |
| 1 | The duplicate failed (error, system_error, aborted), or the command itself failed. |
| 2 | Usage error (a local-only flag on a server target included). |
| 3 | The duplicate was cancelled (attached/followed runs). |
| 4 | The duplicate timed out (attached/followed runs). |
Named errors
--approve-all applies to local execution only — pass --local to run in the repository instead of creating on the server(likewise--follow-logs; exit 2).--refresh-git-rev applies to server targets only …— exit 2 on a local target.run "<id>" is not a change — --refresh-git-rev re-resolves a change's git revision and does not apply to workflow runs— exit 1; the server's own refusal for an asset change (the create lane's named 422) is printed verbatim the same way.--skip-steps has been deprecated, use --skip-step— a warning on stderr; the alias still works.
Examples
Retry a failed run on the server and return immediately:
opschain runs retry 0199c81e-…
Retry, skipping an optional subtree, and follow it to the end:
opschain runs retry 0199c81e-… --skip-step "deploy/optional_bit/**" --follow
Retry a project/environment git change at the branch's latest commit:
opschain runs retry 0199c81e-… --refresh-git-rev
See also
opschain docs cli/runs-show— inspect the failure before retrying.opschain docs cli/runs-create— the lane selection this verb mirrors.opschain docs cli/runs-cancel— stop the duplicate if it goes wrong.opschain learn 3.1— retry in the change walkthrough.