# realm run: commands that act `realm run` has seventeen subcommands. This page covers the eleven that change a run or the store. The six that only read are in [`realm run`: commands that read](https://realmengine.dev/docs/reference/cli/realm-run-reading.md). Every output shown came from a run of the command. | Subcommand | What it does | Acts when | | ------------------------- | ------------------------------------------------------------- | --------------------------- | | [`respond`](#respond) | Answers a gate. | Always | | [`advance`](#advance) | Runs what a run owes the engine, with no model. | Always | | [`resume`](#resume) | Makes a failed step runnable again. | Always | | [`abandon`](#abandon) | Ends an open run. | Always | | [`cleanup`](#cleanup) | Abandons every open run that has been idle for a given time. | Unless `--dry-run` is given | | [`reclaim`](#reclaim) | Frees a step that was started and never finished. | Only with `--force` | | [`drain`](#drain) | Runs the cleanup steps a finished run still owes. | Only with `--force` | | [`purge`](#purge) | Deletes finished runs. | Only with `--force` | | [`gc`](#gc) | Deletes files that a crash left in the store. | Only with `--force` | | [`reconcile`](#reconcile) | Rebuilds the index of idempotency keys. | Unless `--dry-run` is given | | [`migrate`](#migrate) | Records the ending of runs that were written by old versions. | Only with `--force` | A duration is a whole number followed by `d`, `h` or `m`: `30d`, `6h`, `10m`. A run ID that is not in the store gets `Run not found: ` and exit code 1. When the `@sensigo/realm` the workflow's code imports is not the version the command runs, the command prints [`REALM_RELEASE_LINE_MISMATCH`](https://realmengine.dev/docs/reference/workflow/loader-diagnostics.md#warning-codes) to stderr once per copy and goes on. This was added in 0.46.0. ## `respond` ```text realm run respond --gate --choice [--by ] [--project ] [--extensions-module ] ``` Answers the gate a run is waiting at. `realm run inspect ` prints the gate's ID and its choices. | Flag | Required | What it does | | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--gate ` | Yes | The ID of the open gate. | | `--choice ` | Yes | One of the gate's choices. | | `--by ` | No | Who made the choice. Recorded with the answer as given, and not checked. At most 200 characters, no control characters. Added in 0.46.0. | | `--project ` | No | Used only for a workflow registered without a project folder (made by an agent or from a string): the folder whose `realm.yaml` and code it loads. Default: the current folder. A workflow registered from a folder loads its code from there, and `--project` is not used (the command says so). | | `--extensions-module ` | No | Loads this code file in place of the files named by the workflow's `extensions`. | ```bash realm run respond 3ebc1158-1d29-41b5-9ca5-df054a681b58 --gate 0d499c26-a6b4-406f-ae29-6d6ef5c75fcb --choice approve ``` ```text Responded: 3ebc1158-1d29-41b5-9ca5-df054a681b58 | choice 'approve' | new state 'running' ``` `new state` is the run's phase after the answer: `running` if steps remain, `completed` if the gate's step was the last. When the answer leaves `auto` steps that only the engine can run, one more line names them and the command that runs them (`runs it` for one step, `runs them until a step opens a question, fails or ends the run` for more: see [`advance`](#advance)), where that command loads the steps' project code from (the workflow's own project folder, whatever folder the shell is in; for a workflow made without one, the folder it runs in or its `--project`), and that the environment is that shell's. Added after version 0.46.0: ```text Responded: b178179a-998d-457e-85e6-6d38439d0585 | choice 'approve' | new state 'running' Owed to the engine: 'process', 'notify' — realm run advance b178179a-998d-457e-85e6-6d38439d0585 runs them until a step opens a question, fails or ends the run, with the project code under /home/me/project, in the environment of the shell it runs in. If a realm workflow run or realm agent is still waiting on this run, it goes on by itself; the line above is for when none is. ``` When the workflow's own project folder holds no project code (no `realm.yaml`, no extension module), the line says `with no project code (nothing to load under )` instead. When `--project` is given for a workflow that has its own project folder, the first line says it was not used: `--project was not used: workflow '' has its own project, , and its code is loaded from there.`, or, when that folder holds no project code, `… has its own project, (no project code there).` Both added after version 0.46.0. With `--extensions-module`, that folder's extension modules are not loaded, and the line ends `…, and its realm.yaml is loaded from there.`, or `… (no realm.yaml there).` when it has none. When the answer leaves an agent step ready, the line says so in the words `realm run advance` uses, with the command that drives it. Added after version 0.46.0: ```text Responded: 4168cf62-7ae2-4ed9-a688-e149ccbe06a6 | choice 'approve' | new state 'running' An agent step is ready: 'finish' — drive it with realm agent --run-id 4168cf62-7ae2-4ed9-a688-e149ccbe06a6 --provider --model If a realm workflow run or realm agent is still waiting on this run, it goes on by itself; the line above is for when none is. ``` After the lines that name a command — `Owed to the engine: …`, `An agent step is ready: …` — one more line says that a `realm workflow run` or `realm agent` still waiting on the run goes on by itself (`the lines above are` when there are two): the run's record does not show whether one is waiting, so the line holds either way. Added after version 0.46.0. When the answer leaves nothing that can run from here — no agent step ready, no owed step that can run, only `auto` steps that cannot run — each such step is named, then the way out. Added after version 0.46.0: ```text Responded: 77772f0c-a80d-49d3-b665-4ac186186fd1 | choice 'approve' | new state 'running' 'compute' cannot run (input_schema): Invalid input for step 'compute': the input must have required property 'n'. Run 77772f0c-a80d-49d3-b665-4ac186186fd1 stays open (phase 'running'): for 'compute', the engine gives it no input, so correct its input_schema and register the workflow again; then, after a fix, realm run advance 77772f0c-a80d-49d3-b665-4ac186186fd1 — or end it: realm run abandon 77772f0c-a80d-49d3-b665-4ac186186fd1 ``` A step that needs a handler or adapter this program lacks ends with its own way out (`— load the missing extension, or run the step on a runner that has it.`), and when no step is refused before its claim the last line is `To end the run instead: realm run abandon ` When the answer leaves nothing to name but a step in flight in another program, the line says to wait for it, in the words `realm run advance` uses. Added after version 0.46.0: ```text Responded: 5c1e8a42-3f0b-4d7e-9a61-2b8f0c4d7e13 | choice 'approve' | new state 'running' 'pack' is in flight in another program — wait for it, or see realm run inspect 5c1e8a42-3f0b-4d7e-9a61-2b8f0c4d7e13 ``` `respond` records the answer. Without `--by` the answer names nobody, and `realm run inspect` shows `(not stated)`. With `--by`, the `Responded:` line names the answerer: `Responded: | choice '' | answered by (as stated) | new state ''`. A name is never taken from the operating system or from `REALM_OPERATOR`: those name a program, and `respond` uses `REALM_OPERATOR` only for the cleanup steps its answer runs. An empty, long or control-character name is refused before the run is read: ```text --by: empty; nothing was recorded. Give a name of at most 200 characters with no control characters, or leave it out. ``` A `REALM_OPERATOR` that cannot be used refuses the answer too, even when the workflow has no cleanup steps, because `respond` checks it before it reads the run: ```text REALM_OPERATOR: contains a control character; it is written as the program's name on any cleanup steps the answer lets run, and respond checks it before reading the run, so nothing was recorded. Unset it or give it a name of at most 200 characters with no control characters. ``` The middle word is `empty`, `longer than 200 characters` or `contains a control character`. `respond` never passes a `claim_token`; the answer's proof reads `no claim_token passed` on `inspect`. A guard step that the answer makes ready is decided in the same write, and what it did is printed before the `Responded:` line. No other step runs: the steps that follow run when a driver next calls the run. A guard that passed, with steps still to run: ```text Guard step 'only_if_shipping' passed. Responded: 989c0619-1bda-4b2e-b5e3-4d33d6519a67 | choice 'ship' | new state 'running' An agent step is ready: 'ship' — drive it with realm agent --run-id 989c0619-1bda-4b2e-b5e3-4d33d6519a67 --provider --model If a realm workflow run or realm agent is still waiting on this run, it goes on by itself; the line above is for when none is. ``` A guard that ended the run. `Reason:` is the guard's `abort_message`, and is left out when the guard has none: ```text Guard step 'only_if_shipping' aborted the run. Reason: The order was held. Responded: c267f37e-bddb-46aa-aea2-b14f62ba358e | choice 'hold' | new state 'aborted' ``` The first line is one of three sentences: `Guard step '' aborted the run.`, `Guard step '' failed with a resolution error. Run is terminated.`, or `Guard step '' passed and completed the run.` A guard that failed is listed as a failed step `realm run resume` takes, so the second sentence goes on with the way back in: `To make the failed step runnable again: realm run resume --from ` (added after version 0.46.0). When the run ended and it has cleanup steps, they run in this process, and one line follows for each cleanup step this ending ran or left pending: `finalizer '': `. A cleanup step that completed or failed at an earlier ending, before `realm run resume`, does not run again and gets no line. When one is left `pending` (this program has no handler for it), the next line names the command that runs it: `Cleanup step left pending: '' — to run it with code that has its handler: realm run drain --force` (added after version 0.46.0). Giving the same answer again prints the `Responded:` line again, naming the answerer the record holds (`answered by (as stated)`, or `answered by (not stated)` when you gave `--by` and the record holds no name); it records no new answer. Without `--by`, a repeat of an answer that names nobody prints no `answered by` part, as the first answer did. A recorded name that cannot be printed, which only a record written outside these commands can hold, is shown as `answered by a recorded name that cannot be printed (control characters, or not a name with its source)`, with or without `--by`. A repeat of the recorded answer is printed the same way after the run has ended, with the run's phase (for example `new state 'abandoned'`), and exits 0. The refusal "The run has ended" below is for an answer to a question that was still open when the run ended, for example one whose time ran out with `on_expiry: abort`. An answer that arrives after the gate's time is up is not recorded, and for a gate that was settled with its default choice `Not recorded:` takes the place of `Responded:`. The lines after it are the ones above: what the run owes (added after version 0.46.0). When this answer is the call that carried out the expiry, its first line says so, as `realm run advance`'s does (where the expiry's choice made a guard ready, `respond` prints the guard's line on its own, after the first line; `realm run advance` adds the guard's sentence to the end of its first line): `⚠ gate '' on '' had expired before this call — this respond call first carried out its declared settle_default: the default choice '' was recorded (enacted_via: respond).`, or `… its declared abort: the run ended (enacted_via: respond).` (added after version 0.46.0). See [An answer after the time is up](https://realmengine.dev/docs/reference/workflow/gates.md#an-answer-after-the-time-is-up). **Exit code:** 0 if the call succeeded, otherwise 1. An answer that was recorded exits 0, also when the guard it made ready aborted the run. A late answer that names the choice the gate was settled with exits 0, although it was not recorded. A refused answer exits 1. This differs from `realm workflow run`, which exits 1 for a run that ended as aborted. The refusals: | Case | Message | | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--gate` is not the open gate | `Gate 'wrong' is not the open gate and matches no committed resolution.` | | `--choice` is not one of the choices | `Choice 'maybe' is not valid. Expected one of: approve, reject` | | The gate was answered differently | `Gate '70d76b3b-…' was already resolved with choice 'approve' — your choice 'reject' was not recorded.` | | The gate's time was up, and it was settled with another choice | `Gate '80e024ee-…' was settled by timeout with choice 'hold' — your choice 'ship' was not recorded.`, after the `⚠` line when this answer carried out the expiry. Then what the guard did, if this answer carried out the expiry — a guard that failed goes on with the way back in, `To make the failed step runnable again: realm run resume --from ` (added after version 0.46.0) — the `Not recorded:` line, and what the run owes. | | The run has ended | `Run '00b33778-…' is terminal (aborted); cannot submit a gate response — an aborted run is never resumed; 'realm run purge 00b33778-…' previews what it would remove.` The words after the dash name the way out that kind of ending has, as `submit_human_response` names it: see [A run that has ended](https://realmengine.dev/docs/reference/mcp/tools.md#a-run-that-has-ended). | ## `advance` ```text realm run advance [--project ] [--extensions-module ] ``` Added after version 0.46.0. Runs what a run owes the engine, from this shell — no model provider, no key: first, when the open question's time is up and it declares `on_expiry`, that default or abort (the preview names it as `the expired question on '' (its declared )`, and for a declared default goes on `; then it runs what that leaves owed until a step opens a question, fails or ends the run.`, and the command prints the line from its reply before the steps it runs: `⚠ gate '' on '' had expired before this call — this advance call first carried out its declared settle_default: the default choice '' was recorded (enacted_via: advance).`, or `… its declared abort: the run ended …`; when the default's choice made a guard ready, the guard's sentence follows on the same line: `… (enacted_via: advance). Guard step '' passed.`); then the guards and `auto` steps that are ready. It runs them one at a time, and the steps the run owes after them, and stops at the first step that opens a question, fails or ends the run: a step named after that one does not run in that call. When the preview names more than one, its line says so: `Owed to the engine: 'approve', 'fetch'; it runs them until a step opens a question, fails or ends the run.` It loads the project's extensions exactly as `respond` does (`--project`, `--extensions-module`) — from the workflow's own project folder, whatever folder the shell is in, or, for a workflow made without one, from `--project` or the folder it runs in — names this program with `REALM_OPERATOR` or the OS user (a `REALM_OPERATOR` that cannot be used prints one line and exits 1 before any work), and prints what it is about to do before it runs anything: ```text Advancing run (workflow 'cli-owed-wf') with no project code (nothing to load under /home/me/project), in this shell's environment. This program: tester (from REALM_OPERATOR) · project code: neither side records project code. Last recorded driver: none recorded. Owed to the engine: 'after'. → after Stopped: an agent step is ready: 'finish' — drive it with realm agent --run-id --provider --model If a realm workflow run or realm agent is still waiting on this run, it goes on by itself; the line above is for when none is. Run : phase 'running' ``` Each guard it decides prints `Guard step '' passed.`, also when a later step completes the run, in the order the steps ran: a guard decided before a later step is printed before that step's line. The guard that ended the run prints its sentence (`Guard step '' aborted the run.`) and `Reason:` when it has one. A guard that failed — its path found nothing — is a step that failed: a `Stopped: '' failed: ` line follows, and the exit code is 1, as for an `auto` step that failed. The first line names the folder the project code is loaded from, or says `with no project code (nothing to load under )` when that folder holds none (no `realm.yaml`, no extension module); a `--project` the workflow's own project folder overrides is said on the next line, `--project was not used: workflow '' has its own project, , and its code is loaded from there.`, or `… (no project code there).` when it holds none (both added after version 0.46.0). With `--extensions-module`, the first line names that module, `with the module (--extensions-module)`, followed by `and the realm.yaml of ` only when that folder has a `realm.yaml`, which the command then reads; the folder's extension modules are not loaded, so the `--project` line ends `…, and its realm.yaml is loaded from there.`, or `… (no realm.yaml there).` when it has none. `--project` is used only for a workflow registered without a project folder (`realm run advance --help` says so). The expiry line is printed when the call carries the expiry out, before the steps it led to; every other line in the reply's `warnings` is printed as `⚠ ` after the steps that ran (added after version 0.46.0, which printed only the expiry line, on stderr, after the steps). At an open question the command runs nothing, and its `Nothing is owed to the engine: a question is open — realm run respond …` line is composed from the run's record as the command read it: when another program answers the question meanwhile, the steps that answer made ready are left for the next `realm run advance`. That command, here and in the `Stopped:` line of a question the call opened, gives the choices as `--choice `, a placeholder to replace, or the choice itself when the question has only one. The preview's `project code` words compare the code this program loaded with what the run last recorded: | Words | Means | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `same as the run's last record` | The same files with the same hashes. | | `differs from the run's last record` | Comparable, and different: a code file, an entry module, the `realm.yaml` or the `--extensions-module` override changed. | | `not comparable with the run's last record` | The run records project code and this program loaded none, the two fingerprints were taken under different rules, one was cut short at its size limit, or one side's load failed. | | `not comparable — the run has recorded no project code yet` | This program loaded project code, and the run has recorded none: no program with project code has run a step of it yet, as on a run just created. It is not a mismatch. | | `neither side records project code` | Neither the run nor this program loaded project code. | `Last recorded driver:` names the program on the run's newest evidence entry that names one, with that entry's step and time: ` at step '',