Skip to main content
After this guide, you can start a run of a deployed workflow, follow it to the point where it needs a person, answer it, recover a parked step, and cancel a run that should stop. In the desktop app, the Runs page lists each run with a card to approve, deny, or edit, and the Inbox collects the cards waiting on you; the steps below do the same from the CLI. To drive the graph on your machine without a run, see Test a workflow offline. Verified against lua-cli 3.33.0. Before you begin
  • A workflow pushed with lua push workflow --name <name> and made live with lua workflows deploy <name> -v latest.
  • A user session (lua auth configure): approve, resolve-step, and delete-run refuse an API key.
1

Start a run

start validates the input against the workflow’s inputSchema, creates the run, and returns at once. An idempotency key makes a retried script return the same run instead of a second one.
The first line is ✅ Run <runId> · queued. --follow attaches watch, so --timeout and --wait-for-human apply. A run the organization cannot seat yet is gated and exits 6; a workflow with concurrencyPolicy: 'forbid' and a run in flight prints the blocking run id and exits 1. --correlation-key labels the run for Workflows.signalByKey and runs --correlation-key.
2

Follow it to a human boundary

watch streams the run’s events and ends when the run ends or when a person is needed.
Output
That notice ends the watch with exit 8 and names the verb that resumes the run: approve, resume for a step parked on ctx.suspend(), signal for a signal wait, raise-budget for a budget park, retry-step for a billing hold; an exception park prints ⚠️ run parked on an exception gate — a human decides next. A completed run exits 0, failed or timed_out 4, cancelled or abandoned 5, a consent gate 6.--wait-for-human keeps streaming through every boundary until the run is terminal or --timeout <s> fires with exit 7 and ⏱️ watch: --timeout 3s reached (run still live); Ctrl-C detaches with exit 0 and changes nothing.
3

Read the run and its steps

status prints the run header; --steps adds a table of every step with its kind, status, attempt, and error.
Output
--json prints the platform’s run document: status; suspendedFor and suspensions[], whose suspend.approvalId is the wfa_… id approve needs; gate (kind, code, stepId) on a gated run; nextAction (none, cancel_again, force, raise_budget, top_up); budget (maxCredits, spent, remaining); and steps[] with preview.input and preview.output.
--strict maps a terminal status to the watch exit codes for scripts that poll.
4

Answer or repair the run

Each park names its verb. All take the run id first and refuse with a typed code when the step is not in the state they expect.A re-armed step runs under the same occurrence, so a once() effect that settled is not repeated. Nothing re-runs a terminal run: retry-step answers RUN_TERMINAL, so start a new run.
Local runs only. In deployed code Workflows.resume, signal, and signalByKey fail with resume_unavailable or signal_unavailable, startBatch, setGoal, and goals.* can answer not_implemented, and Workflows.raiseBudget works in neither runtime; start, get, list, and cancel work in both.
5

Cancel a run

A cancel is a request: running steps stop at their next boundary and the run moves to cancellation_requested.
The reply is ✅ cancel accepted · run <runId> is <status> plus what to do next: next: cancel again to escalate, or next: force available at <time> — lua workflows cancel <runId> --force. A forced cancel abandons the run; a run that already ended answers ℹ️ run <runId> was already <status> — nothing to cancel.
6

Verify

List the workflow’s runs, then read one run’s progress and lifecycle events.
Output
runs filters by --workflow, --status, --correlation-key, and --tag, sorts with --sort, and prints the next page’s command. logs returns the latest 500 progress and lifecycle events, --step <id> narrows to one step, and --follow switches to watch; --since is accepted but has no effect.

​
Options you may need

​
Activate, deactivate, and deploy

lua workflows activate <name> turns the workflow’s schedules and triggers on and deactivate pauses them; neither changes the live version. activate -v <version> is the same as deploy <name> -v <version>: it makes that version live for new runs and records an agent version, so lua version promote <n> is the rollback. A run keeps the version it started on; neither a deploy nor a promote moves a run in flight. Workflows are not part of lua push all, and lua deploy has no workflow type; see Release an agent.

​
Run statuses and exit codes

Other refusals follow the lua workflows table: 1 API refusal, 2 usage, 3 not found, 9 not signed in, 10 forbidden, 11 unavailable. --json prints the platform’s { success, data } or { success: false, error } envelope and keeps the exit code.

​
If it isn’t working

The step is not in a state retry-step or resolve-step can act on. status --steps names it: a running step needs time, a suspended one needs approve, resume, or signal.
The run has ended, so no step can be retried or resolved. Start a new run.
Only a run parked on its budget takes a raise, and only above its current cap. A run at its raise cap must be canceled and started again with a larger --budget-credits.

​
Next steps

Approvals and signals

Approver kinds, editable payloads, and delivering signals from code.

lua workflows reference

Every verb, flag, and refusal code.

Workflows runtime API

Start, signal, resume, and cancel runs from tools and webhooks.

REST API

The routes behind each verb.