> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows Command

> Manage workflows and their runs from the CLI - list, deploy, start, watch, approve, signal, cancel, retry, replay, archive and inspect Job-tier steps

## 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.

```bash theme={null}
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
```

<Note>
  For writing workflows see [Authoring](/workflows/authoring). For the run model behind these verbs see [Runs and events](/workflows/runs-and-events).
</Note>

## 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.

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
lua workflows run outreach --input @leads.json --step-output draftEmail=@draft.json --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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
lua workflows job-logs wfr_3f2... implement --tail 500 --follow
```

## Push, deploy and versions

Workflows follow the same release flow as every other primitive:

1. **`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.
2. **`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.
3. **`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.

```bash theme={null}
lua push workflow --name outreach
lua workflows versions outreach
lua workflows deploy outreach -v latest
lua workflows start outreach --input @leads.json --follow
```

## Related

* [Workflows](/overview/workflows) - the concept
* [Workflows Quick Start](/workflows/quick-start)
* [Authoring](/workflows/authoring) and [Job tier](/workflows/job-tier)
* [Runs and events](/workflows/runs-and-events) - the run model these verbs act on
* [Version Command](/cli/version-command) - agent versions and rollback
* [Push & Deploy](/cli/skill-management#lua-push)