Workflows Command

Overview

lua workflows manages workflow definitions and runs. Definitions are pushed with lua push workflow and activated with lua workflows deploy; runs are started, watched and steered with the run verbs.

lua workflows                                      # Interactive: list, run locally, start, list runs
lua workflows list                                 # Workflows on the agent
lua workflows deploy outreach -v latest            # Make the newest version live
lua workflows start outreach --input @leads.json --follow
lua workflows runs --workflow outreach --status failed
lua workflows status <runId> --steps
lua workflows approve <runId> --approval <id> --decision approve

For writing workflows see Authoring. For the run model behind these verbs see Runs and events.

Usage

lua workflows [action] [target] [extra] [options]

target is the workflow name (or id) for list, view, versions, deploy, activate, deactivate, start, run, env-overlay and delete; a run id for every other verb. -i <name> / -r <runId> are the equivalent options.
extra is the signal name for signal <runId> <name> and the step id for job-logs <runId> <stepId>.

Subcommands

Action	What it does
`list`	List workflows on the agent (`--all` includes dynamic ones).
`view`	Show one workflow: status, active version, schedule, output visibility, env overlay keys, versions.
`versions`	List every version of a workflow.
`deploy`	Make a version active (`-v <ver>` or `latest`).
`activate` / `deactivate`	Enable or pause a workflow’s schedules and triggers. `activate -v <ver>` also deploys that version.
`start`	Start a run.
`run`	Run a workflow locally (alias of `lua test workflow`; no API call).
`runs`	List runs.
`status`	Show one run (and its steps with `--steps`).
`watch`	Stream a run’s events until it ends or waits for a person.
`cancel`	Request (or force) a cancel.
`resume`	Resume a step parked by `ctx.suspend()`.
`retry-step`	Re-arm a failed, parked or billing-held step.
`approve`	Approve or deny an approval.
`signal`	Deliver a signal.
`replay`	Replay a run locally against the compiled artifact.
`logs`	Print a run’s progress and log events.
`delete`	Delete a workflow.
`delete-run`	Erase a terminal run.
`env-overlay`	Show which `env.template()` keys a version carries and whether each is present.
`archive-runs`	Export terminal runs as evidence bundles to a directory.
`workspace`	Show or release a run’s Job-tier workspace.
`jobs`	List a run’s Job-tier steps.
`job-logs`	Print a Job-tier step’s container log.

Common options

Option	Description
`-i, --workflow-name <name>`	Workflow name or id (instead of the positional target).
`-r, --run-id <id>`	Run id (instead of the positional target).
`-v, --workflow-version <ver>`	Version for `deploy`, `activate`, `env-overlay` and `start` (`latest` allowed).
`--json`	Print the raw `{ success, data }` envelope. Pipe to `jq`.

Exit codes

Code	Meaning
`0`	Success.
`1`	Server or API failure.
`2`	Usage error.
`3`	Not found.
`4`	The run ended `failed` or `timed_out` (also a replay divergence).
`5`	The run ended `cancelled` or `abandoned`.
`6`	The run is gated awaiting consent.
`7`	`--timeout` reached while the run was still live.
`8`	The run is parked on a person or a gate (approval, input, signal, exception, billing, budget).

Definitions

`lua workflows list`

Option	Description
`--all`	Include dynamic (server-composed) workflows.

Columns: Name, Status, Active version, Versions, Form (static / dynamic), Id.

`lua workflows view <name>`

Prints the workflow’s id, status, active version, schedule, output visibility (roles, users, owner bypass), env overlay keys, and a versions table (version, form, topology, graph hash, created).

`lua workflows versions <name>`

The versions table alone.

`lua workflows deploy <name> -v <ver|latest>`

Publishes a version as the active one. On an agent under versioning this is a scoped promote: a new agent version is recorded and printed as agentVersion. Without -v the newest version is deployed.

lua workflows deploy outreach -v 1.0.3
lua workflows deploy outreach -v latest

`lua workflows activate <name>` / `deactivate <name>`

Enable or pause the workflow’s schedules and triggers. activate -v <ver> is the same as deploy.

`lua workflows delete <name>`

Option	Description
`--yes`	Skip the confirmation prompt.
`--force`	Cancel in-flight runs first. Without it a workflow with runs in flight is refused (409 `RUNS_IN_FLIGHT` with counts).

Remove the file from src/workflows/ (and its entry in lua.skill.yaml) afterwards to keep the project in sync.

`lua workflows env-overlay <name> [-v <ver|latest>]`

Lists every env.template() key on the version, where it resolved from, and whether it is present in the agent environment. Values are never printed. Exits 1 when a key is missing.

Starting and running

`lua workflows start <name>`

Option	Description
`--input <json\|@file>`	Run input (default `{}`).
`--idempotency-key <key>`	Reusing a key returns the original run (`idempotent replay`).
`--correlation-key <key>`	Caller-chosen, non-unique key for finding and signalling the run later.
`--tag <tag>`	Repeatable, at most 10.
`--budget-credits <n>`	Run budget in credits.
`--wait <s>`	Server long-poll, 0..55 s: returns the settled run when it finishes inside the window.
`--follow`	Attach `watch` after the start.
`-v, --workflow-version <ver>`	Pin a version instead of the active one.

Prints Run <runId> · <status> and, without --follow, the watch and status commands to run next. A gated start exits 6; a concurrencyPolicy: 'forbid' workflow with a run in flight prints the blocking run id and exits 1.

lua workflows start outreach --input '{"leads":[]}' --follow
lua workflows start ticket-plan --input @ticket.json --idempotency-key ticket-plan:TP-12 --tag triage

`lua workflows run <name>`

Runs the workflow locally after compiling the project - the same as lua test workflow --name <name>. No run is created on the server.

Option	Description
`--input <json\|@file>`	Run input.
`--step-output <id=json>`	Complete a step with this output (repeatable).
`--approve <id[=@payload]>`	Pre-answer an approval (repeatable).
`--deny <id[=@reason]>`	Pre-deny an approval (repeatable).
`--signal <name=json>`	Pre-supply a `waitForSignal` payload (repeatable).
`--from-run <runId>`	Seed completed steps from a real run.
`--force`	Seed from a run whose graph differs.
`--record <dir>`	Record agent and tool outputs as fixtures.
`--fixtures <dir>`	Replay recorded fixtures.
`--step-wall <s>`	Per-step wall in seconds (default 600).
`--job-wall <s>`	Virtual wall for `tier: 'job'` steps; splits at 14 400 s segments, above 86 400 is a usage error.
`--ledger-out <file>`	Write the in-memory ledger as JSON.
`--agents <fake\|live>`	Fake agent steps (default) or call the dev API.
`--now <iso>`	Virtual clock start.
`--park <id>`	Simulate a platform-fault park of a step (repeatable).
`--fast-retries`	Collapse retry backoff waits to 0.
`--real-time`	Actually wait on sleeps and backoffs.
`--artefacts-dir <dir>`	Back `ctx.artefacts.*` on disk.
`--env <KEY=value>`	Local `env.template()` overlay (repeatable; a missing key is a usage error).
`--max-ticks <n>`	Script form: tick cap (default 64).

Interactive runs prompt on stdin for any approval, input or signal you did not pre-answer.

lua workflows run outreach --input @leads.json --step-output [email protected] --approve reviewDrafts

Runs

`lua workflows runs`

Option	Description
`--workflow <name>`	Filter by workflow.
`--status <status>`	Filter by status.
`--correlation-key <key>`	Filter by correlation key.
`--tag <tag>`	Filter by tag (repeatable).
`--limit <n>`	Page size.
`--cursor <c>`	Page cursor (printed at the end of a page).
`--sort <field>`	`-createdAt` (default), `createdAt`, `-durationMs`, `durationMs`.

Columns: Run, Status, Trigger, Created, Correlation, Tags.

`lua workflows status <runId>`

Option	Description
`--steps`	Fetch the full run and print a per-step table (Step, Kind, Status, Attempt, Error).
`--strict`	Exit `4` / `5` by terminal status instead of `0`.

Prints the run’s status, workflow and version, trigger, correlation key and tags, timings, lineage, gate (with the action that clears it), failure reason and output. A run whose outputs are restricted prints restricted instead of the output.

`lua workflows watch <runId>`

Streams the run’s events over SSE and prints one line per event. Reconnects from the last event id when the stream drops. Stops at the terminal event (exit 0, 4 or 5) or as soon as the run waits for a person or a gate (exit 8), printing the verb that resumes it.

Option	Description
`--after <seq>`	Replay from this sequence number.
`--timeout <s>`	Give up after `s` seconds while the run is still live (exit `7`).
`--events`	Print raw frames as JSON (`{ id, event, data }`) instead of the formatted line.

step.throttled events are collapsed into one counter line. Press Ctrl-C to detach without affecting the run.

`lua workflows logs <runId>`

Fetches the run’s events once (polling form, up to 500) and prints the progress and lifecycle ones: step.progress (your ctx.log messages), *.started, *.completed, *.failed, *.skipped, run.log.

Option	Description
`--step <id>`	Only this step’s events.
`--follow`	Switch to `watch`.
`--since <dur>`	Window (accepted; see note).

`lua workflows cancel <runId>`

Option	Description
`--reason <text>`	Recorded on the run.
`--force`	Force cancel once the server says force is available.

Prints the verdict and the next action (cancel again or force available at ...).

`lua workflows resume <runId> --step <id>`

Option	Description
`--step <id>`	The suspended step. Required.
`--data <json\|@file>`	The `resumeData` (must match the step’s `resumeSchema`).

Refused with a hint when the step is an approval (use approve) or a signal wait (use signal). A repeated resume prints who already resumed it.

`lua workflows retry-step <runId> --step <id>`

Option	Description
`--step <id>`	The parked step. Required.
`--note <text>`	Recorded with the retry.

Re-arms a step that failed past its retries, parked on an exception gate, or sits on a billing hold (the only way out of a billing park after topping up). 409 STEP_NOT_PARKED when the step is running, pending or already re-armed; RUN_TERMINAL when the run ended.

`lua workflows approve <runId> --approval <id>`

Option	Description
`--approval <id>`	The approval id (`wfa_...`). Required.
`--decision <approve\|deny>`	Default `approve`.
`--note <text>`	The approver’s note (the workflow reads it as `note`).
`--edit <json\|@file>`	An edited payload (small inline edits).
`--fingerprint <f>`	The payload fingerprint you looked at. Mandatory with `--edit`; a stale one is 409 `PAYLOAD_MISMATCH`.

Find the approval id with lua workflows status <runId> --json (data.suspensions[].suspend.approvalId) or in the desktop card. STEP_UP_REQUIRED means the approval must be given from the desktop with a fresh login.

lua workflows approve wfr_3f2... --approval wfa_9c1... --decision approve --note "Go ahead"
lua workflows approve wfr_3f2... --approval wfa_9c1... --decision deny

`lua workflows signal <runId> <name>`

Option	Description
`--payload <json\|@file>`	The signal payload (validated against the wait’s `schema`).
`--dedupe-key <key>`	Makes a redelivery a no-op.

Prints whether the signal was consumed by a step, parked until a step waits for it, or was a duplicate.

lua workflows signal wfr_3f2... review --payload '{"ok":true}' --dedupe-key review:42

`lua workflows replay <runId> --local`

Re-derives the run from the compiled artifact in the current project and compares each step’s recorded output with the local derivation. A differing graph hash is reported first. Exit 4 on a divergence. Only --local is available; pass -i <name> when several compiled workflows could match.

`lua workflows delete-run <runId>`

Erases a terminal run - outputs, artefacts and journal. Prompts unless --yes. A live run is refused (cancel it first).

Archiving

`lua workflows archive-runs --since <iso|dur> --out <dir>`

Exports every terminal run in the window as an evidence bundle, verifies each download against its manifest hash, writes <runId>.zip files and an archive-index.ndjson, and skips runs already archived with a matching hash.

Option	Description
`--since <iso\|dur>`	Window start (`8d`, `36h`, `90m` or an ISO timestamp). Required.
`--out <dir>`	Destination directory. Required.
`--until <iso>`	Window end.
`--workflow <name>`	Only this workflow’s runs.
`--tag <tag>`	Only runs with this tag (repeatable).
`--concurrency <n>`	Parallel exports, 1..5 (default 2).
`--no-inputs`	Exclude run inputs from the bundles.
`--no-artefacts`	Exclude artefacts from the bundles.
`--retention-days <n>`	Your organisation’s run retention (default 90). `--since` must be inside retention minus the 7-day export TTL, otherwise `ARCHIVE_WINDOW_TOO_OLD`.
`--connection <id>`	Storage connection for `s3://` / `gs://` sinks - not available in this build; archive to a local directory and sync it.

Exit 3 when the window holds no terminal runs, 4 when any export failed or was deferred (rate-limited or still pending).

Job tier

`lua workflows workspace <runId>`

Shows the run’s workspace: kind and backend, repo and ref, branch and head, size used, files changed, TTL, worktree arms (branch, head, pushed, merged, conflicts) and any error.

Option	Description
`--release`	Release the volume now. Refused with the step id while a step is using it.
`--note <text>`	Recorded with the release.

`lua workflows jobs <runId>`

Lists the run’s tier: 'job' steps: Step, Status, Attempt, Size class, Pod phase, Segment, Heartbeat, Error.

`lua workflows job-logs <runId> <stepId>`

Option	Description
`--attempt <n>`	Attempt to read (default latest).
`--tail <n>`	Log lines, 1..2000 (default 200).
`--follow`	Poll every 5 s until the step is terminal.

Prints a header (attempt, status, pod phase, size class, segment, harness, pod name, last heartbeat, error) followed by the log lines.

lua workflows job-logs wfr_3f2... implement --tail 500 --follow

Push, deploy and versions

Workflows follow the same release flow as every other primitive:

lua push workflow compiles the project and mints a new immutable version of each changed workflow (--name <name> for one; aliases workflows and wf). Missing env.template() keys abort the push before anything is sent. lua push all does not include workflows - push them explicitly. --auto-deploy publishes the version straight after the push.
lua workflows deploy <name> -v latest activates the version. On an agent under versioning this records a scoped promote - a new agent version identical to the current one except for this workflow - and prints its number.
lua version snapshots pin workflow versions alongside skills, webhooks and jobs, so lua version promote <N> rolls a workflow back with everything else. lua version create after a push captures the newest pushed workflow versions.

lua push workflow --name outreach
lua workflows versions outreach
lua workflows deploy outreach -v latest
lua workflows start outreach --input @leads.json --follow

Workflows - the concept
Workflows Quick Start
Authoring and Job tier
Runs and events - the run model these verbs act on
Version Command - agent versions and rollback
Push & Deploy

​Overview

​Usage

​Subcommands

​Common options

​Exit codes

​Definitions

​lua workflows list

​lua workflows view <name>

​lua workflows versions <name>

​lua workflows deploy <name> -v <ver|latest>

​lua workflows activate <name> / deactivate <name>

​lua workflows delete <name>

​lua workflows env-overlay <name> [-v <ver|latest>]

​Starting and running

​lua workflows start <name>

​lua workflows run <name>

​Runs

​lua workflows runs

​lua workflows status <runId>

​lua workflows watch <runId>

​lua workflows logs <runId>

​lua workflows cancel <runId>

​lua workflows resume <runId> --step <id>

​lua workflows retry-step <runId> --step <id>

​lua workflows approve <runId> --approval <id>

​lua workflows signal <runId> <name>

​lua workflows replay <runId> --local

​lua workflows delete-run <runId>

​Archiving

​lua workflows archive-runs --since <iso|dur> --out <dir>

​Job tier

​lua workflows workspace <runId>

​lua workflows jobs <runId>

​lua workflows job-logs <runId> <stepId>

​Push, deploy and versions

​Related

Overview

Usage

Subcommands

Common options

Exit codes

Definitions

`lua workflows list`

`lua workflows view <name>`

`lua workflows versions <name>`

`lua workflows deploy <name> -v <ver|latest>`

`lua workflows activate <name>` / `deactivate <name>`

`lua workflows delete <name>`

`lua workflows env-overlay <name> [-v <ver|latest>]`

Starting and running

`lua workflows start <name>`

`lua workflows run <name>`

Runs

`lua workflows runs`

`lua workflows status <runId>`

`lua workflows watch <runId>`

`lua workflows logs <runId>`

`lua workflows cancel <runId>`

`lua workflows resume <runId> --step <id>`

`lua workflows retry-step <runId> --step <id>`

`lua workflows approve <runId> --approval <id>`

`lua workflows signal <runId> <name>`

`lua workflows replay <runId> --local`

`lua workflows delete-run <runId>`

Archiving

`lua workflows archive-runs --since <iso|dur> --out <dir>`

Job tier

`lua workflows workspace <runId>`

`lua workflows jobs <runId>`

`lua workflows job-logs <runId> <stepId>`

Push, deploy and versions

Related