ironflow run

List and inspect workflow runs, and control them: cancel, delete, prune, redact, pause, inject step output, and resume.

ironflow run <subcommand> [flags]

ironflow run list

List workflow runs with optional filtering.

ironflow run list [flags]

Flags:

Flag	Short	Type	Default	Description
--server	-s	string		Server URL override
--function		string		Filter by function ID
--status		string		Filter by status (waiting_for_capacity, waiting, running, completed, failed, cancelled, paused)
--limit		int	50	Maximum number of runs to return
--json		bool	false	Output as JSON

Output:

ID      FUNCTION         STATUS     STARTED
run-1   stripe-handler   completed  2025-01-15 12:00:05
run-2   order-process    failed     2025-01-15 11:59:30

With --json, the command prints an array of objects. Each object has id, function (the function ID) and status. It adds started_at and ended_at (UTC, 2006-01-02T15:04:05Z format) only when the run has them. With no matches, the array is empty.

ironflow run get

Get detailed information about a specific workflow run.

ironflow run get <run-id> [flags]

Arguments:

Argument	Required	Description
run-id	Yes	The run ID to look up

Flags:

Flag	Short	Type	Default	Description
--server	-s	string		Server URL override
--json		bool	false	Output as JSON

Output:

ID:        run-abc123
Function:  stripe-handler
Status:    completed
Mode:      push
Event:     evt_01HN8K3X5Y
Started:   2025-01-15T12:00:05Z
Ended:     2025-01-15T12:00:06Z
Duration:  1.2s

The Event, Worker, Started, Ended, Duration, Attempt and Error lines appear only when the run has a value for them.

ironflow run wait

Block until a run is completed, failed or cancelled, or has paused after exhausting its retries, then print it. Use it after ironflow run resume, or with a run ID from emit or invoke --no-wait, instead of polling ironflow run get.

ironflow run wait <run-id> [flags]

Arguments:

Argument	Required	Description
run-id	Yes	The run ID to wait for

Flags:

Flag	Short	Type	Default	Description
--timeout	-t	duration	30s	How long to wait before giving up
--json		bool	false	Output as JSON
--server	-s	string		Server URL override

The run is printed in the same format as ironflow run get. Exit code 0 means the run completed. Exit code 1 means it failed, was cancelled, paused after exhausting its retries, or was still not finished at --timeout. A run paused with reason retries_exhausted waits for an operator, so the command returns at once instead of waiting out the timeout; resume it with ironflow run resume <run-id>. A run that is blocked on an event or an approval shows status waiting. Waiting never cancels the run.

ironflow run cancel

Cancel a queued, running, or paused workflow run.

ironflow run cancel <run-id> [flags]

Arguments:

Argument	Required	Description
run-id	Yes	The run ID to cancel

Flags:

Flag	Short	Type	Default	Description
--reason		string		Cancellation reason
--server	-s	string		Server URL override

Output:

Canceled run run-abc123 (status: cancelled)

Examples:

ironflow run list
ironflow run list --function stripe-handler --status failed
ironflow run list --limit 10 --json
ironflow run get run_abc123
ironflow run get run_abc123 --json
ironflow run cancel run_abc123
ironflow run cancel run_abc123 --reason "no longer needed"

ironflow run delete

Permanently delete a single terminal run and its steps.

ironflow run delete <run-id> [flags]

The run must already be in a terminal state (completed, failed, or cancelled) — cancel it first otherwise. Destructive; prompts for confirmation unless --yes is passed. Needs the runs:delete action, which only the admin role holds by default.

On PostgreSQL, the command fails with an aborted error while another call holds the run, a child run, a step, or its capacity. Retry it.

Arguments:

Argument	Required	Description
run-id	Yes	The run ID to delete

Flags:

Flag	Short	Type	Default	Description
--server	-s	string		Server URL override
--yes		bool	false	Skip confirmation prompt

Output:

Deleted run run-abc123

Examples:

ironflow run delete run_abc123
ironflow run delete run_abc123 --yes

ironflow run redact

Irreversibly replace a run’s input and output, its error and every child step’s error — and the error of every recorded attempt and the payload of every audit row, for that run and its steps — with a placeholder.

ironflow run redact <run-id> [flags]

The rows, their ids and their statuses all stay; only the stored payloads go, so listings, reconstruction and the audit trail still show what happened. The placeholder is {"$redacted": true, "sha256": "...", "redactedAt": "..."}; the hash is of the original bytes and nothing recovers them from it.

The run must already be in a terminal state, because a resume reads input. A step’s own output columns are left alone — use ironflow run redact-step for those. Destructive and irreversible; prompts for confirmation unless --yes is passed. Needs the events:redact action, which only the admin role holds by default.

Error envelopes are replaced whole, including message, code, stack, details and encrypted envelopes. Stored error placeholders survive later writes, including failures after a resume. Empty errors stay absent.

Three things this does not reach:

• A copy already published to a stream survives until its own retention window expires (seven days on PUBSUB; EVENTS has no age expiry and requires terminal reclamation).
• Object-storage copies can remain until a successful cleanup sweep. Permanent markers authorize repeated cleanup of the run’s payload prefix; they do not authorize sweeping its steps’ artifact prefixes. See redaction limits.
• Projection state is not rewritten. A read model that folded these payloads into its state keeps them; Ironflow never edits projection state, on a delete or a redaction. Rebuild the projection with ironflow projection rebuild if it needs to forget them too.

Arguments:

Argument	Required	Description
run-id	Yes	The run ID to redact

Flags:

Flag	Short	Type	Default	Description
--server	-s	string		Server URL override
--yes		bool	false	Skip confirmation prompt

Output:

Redacted run run-abc123

Examples:

ironflow run redact run_abc123
ironflow run redact run_abc123 --yes

ironflow run redact-step

Irreversibly replace one step’s output, original output and error, and its parent run’s error — and the error of each of its recorded attempts, the errors of the run’s run-level retries and the payload of every audit row for that step — with a placeholder.

ironflow run redact-step <step-id> [flags]

The parent run’s error is always scrubbed because SDKs copy step failures into it without reliable step provenance. Sibling step errors are unchanged. Error envelopes are replaced whole.

step-id is the step’s row id, not the step name. ironflow run get does not print it. Read it from the id column of the steps table, for example ironflow sql "SELECT id, step_id FROM steps WHERE run_id = '<run-id>'". Output and original output always go together: they share one object-storage prefix, so removing one and sweeping the prefix would leave the other unreadable.

The run must already be in a terminal state, because a memoized resume reads output. Same caveats as ironflow run redact above.

A step’s output is normally copied into the run’s output as well, so redacting the step alone usually leaves a copy behind. Run ironflow run redact on the same run to reach it. Needs the events:redact action.

Arguments:

Argument	Required	Description
step-id	Yes	The step’s row id (not its name)

Flags:

Flag	Short	Type	Default	Description
--server	-s	string		Server URL override
--yes		bool	false	Skip confirmation prompt

Output:

Redacted step 01JD2KQ...

Examples:

ironflow run redact-step 01JD2KQ7X8Y9Z
ironflow run redact-step 01JD2KQ7X8Y9Z --yes

ironflow run prune

Permanently delete every terminal run matching a filter in the current environment.

ironflow run prune [flags]

At least one of --function, --status, --before is required. Destructive; prompts for confirmation unless --yes is passed. Needs the runs:delete action, which only the admin role holds by default.

The server caps one DeleteRuns call at 10,000 runs, so run prune re-issues the same filter until the server reports zero (a count below the cap does not mean drained) and prints the total across all calls. A failure partway through reports how many it already deleted — those runs are gone, so re-run the same command to continue. On PostgreSQL, a run stays behind while another call holds its rows, so a later run prune can delete more.

Flags:

Flag	Short	Type	Default	Description
--function		string		Filter by function ID
--status		string		Filter by terminal status (completed, failed, cancelled)
--before		string		Filter to runs created before this RFC3339 timestamp or YYYY-MM-DD date (UTC)
--server	-s	string		Server URL override
--yes		bool	false	Skip confirmation prompt

Output:

Deleted 3 runs

Examples:

ironflow run prune --status completed --before 2025-01-01
ironflow run prune --function my-func --yes

ironflow run pause

Pause a running workflow at the next step boundary for inspection and injection.

ironflow run pause <run-id> [flags]

If the run is currently executing, sets a pause flag that is consumed at the next step boundary. A waiting run immediately transitions to an explicit paused hold with the injection reason.

Arguments:

Argument	Required	Description
run-id	Yes	The run ID to pause

Flags:

Flag	Short	Type	Default	Description
--server	-s	string		Server URL override

Output:

Run run-abc123: paused

Examples:

# Pause a running workflow
ironflow run pause run_abc123

# Pause against a different server
ironflow run pause run_abc123 --server http://prod:9123

ironflow run paused-state

View completed steps and their outputs for a run paused for injection.

ironflow run paused-state <run-id> [flags]

Only works on runs with pause_reason = "injection". Shows each completed step’s ID, name, whether it was injected, and its output. Also displays the pause reason and next step hint if available.

Arguments:

Argument	Required	Description
run-id	Yes	The paused run ID to inspect

Flags:

Flag	Short	Type	Default	Description
--json		bool	false	Output as JSON
--server	-s	string		Server URL override

Output:

Pause reason: injection
Next step:    send-notification

ID          NAME              INJECTED  OUTPUT
step_001    validate-input              {"valid":true}
step_002    process-order               {"order_id":"123","total":99.99}

Examples:

# View paused state
ironflow run paused-state run_abc123

# JSON output for scripting
ironflow run paused-state run_abc123 --json

ironflow run inject

Modify the output of a completed step while a run is paused for injection.

ironflow run inject <run-id> <step-id> [flags]

Replaces the step’s output with new data. The original output is preserved in original_output for audit purposes. An audit event (step.injected) is emitted if the function has recording enabled.

Arguments:

Argument	Required	Description
run-id	Yes	The paused run ID
step-id	Yes	The completed step ID to modify

Flags:

Flag	Short	Type	Default	Description
--output		string		New JSON output for the step (required)
--reason		string		Reason for the injection (optional)
--server	-s	string		Server URL override

Output:

Injected step step_002
Previous output: {"order_id":"123","total":99.99}

Examples:

# Inject modified output
ironflow run inject run_abc123 step_002 --output '{"order_id":"123","total":89.99}'

# Inject with a reason for the audit trail
ironflow run inject run_abc123 step_002 \
  --output '{"corrected": true}' \
  --reason "Fix calculation error"

ironflow run resume

Resume a paused or failed run. When resuming an injection-paused run, clears the pause state and re-dispatches from where it left off.

A run paused with reason retries_exhausted (it used up its retry attempts) and a failed run both get a fresh retry budget on resume: the attempt number is kept and the run gets as many more attempts as its function’s retry policy allows. Fix the cause first, because a resumed run that fails again retries with backoff before it pauses again.

ironflow run resume <run-id> [flags]

Arguments:

Argument	Required	Description
run-id	Yes	The run ID to resume

Flags:

Flag	Short	Type	Default	Description
--from-step		string		Resume from a specific step ID
--server	-s	string		Server URL override

Output:

Resumed run run-abc123 (status: running)

A second resume of the same run within about 2 minutes of the first returns a conflict (HTTP 409 on the REST API, exit code 7 in the CLI), even after the first resume has finished. The server does not queue it, and the run stays in its earlier state.

Examples:

# Resume a paused run
ironflow run resume run_abc123

# Resume from a specific step
ironflow run resume run_abc123 --from-step step_002

# Typical scoped injection workflow
ironflow run pause run_abc123
ironflow run paused-state run_abc123
ironflow run inject run_abc123 step_002 --output '{"fixed": true}' --reason "correct value"
ironflow run resume run_abc123

---