# struere workflows

> Manage workflows and inspect, fire, and recover workflow runs

The `workflows` command lists [graph-based workflows](/platform/workflows), inspects their runs node-by-node, fires them manually, enables/disables them, and recovers failed runs. Workflows are authored as code with [`defineWorkflow`](/sdk/define-workflow) in the `workflows/` directory and synced with `struere dev` / `struere sync`; this command is for operating them.

## Usage

```bash
bunx struere workflows list
bunx struere workflows get <slug>
bunx struere workflows runs [slug]
bunx struere workflows run <run-id>
bunx struere workflows logs [slug]
bunx struere workflows log <identifier>
bunx struere workflows stats
bunx struere workflows fire <slug>
bunx struere workflows enable <slug>
bunx struere workflows disable <slug>
bunx struere workflows cancel <run-id>
bunx struere workflows retry <run-id>
bunx struere workflows import-trigger <slug>
```

Running `struere workflows` with no subcommand is equivalent to `struere workflows list`.

## Authoring vs operating

You **author** a workflow as a file and sync it; you **operate** it with this command:

```bash
bunx struere add workflow vip-payment   # scaffold workflows/vip-payment.ts
bunx struere dev                        # watch workflows/ and sync on save
bunx struere sync                       # one-shot sync, then exit
```

`struere dev` watches the `workflows/` directory alongside `agents/`, `routers/`, and `triggers/`. See [struere add](/cli/add) and [defineWorkflow](/sdk/define-workflow).

## Subcommands

### workflows list

List all workflows with their trigger, node count, enabled state, and last-run status.

```bash
bunx struere workflows list
bunx struere workflows list --env production
bunx struere workflows list --failed --json
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--failed` | Show only workflows whose most recent run was `failed`, `dead`, or `completed_with_errors` |
| `--json` | Output results as JSON |

The output table shows Name, Slug, Trigger (e.g. `cron 0 9 * * 5`, `payment.updated`, or `manual`), Nodes, Enabled, Last Run status, and Updated time.

### workflows get

View a workflow's metadata and its graph — every node with its type and the nodes each output port connects to.

```bash
bunx struere workflows get vip-payment
bunx struere workflows get vip-payment --env production --json
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |

Each node line shows its name, `[type]`, and per-port edges (e.g. `port0→VIP perk | port1→Standard thanks`).

### workflows runs

List runs, optionally for a single workflow.

```bash
bunx struere workflows runs
bunx struere workflows runs vip-payment
bunx struere workflows runs --status completed_with_errors --limit 50
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--status <status>` | Filter by status: `pending`, `running`, `completed`, `completed_with_errors`, `failed`, or `dead` |
| `--limit <n>` | Maximum results. Default: `20` |
| `--json` | Output results as JSON |

The table shows the run ID, workflow slug, status, dedupe key, error (if any), and time.

### workflows run

View a single run in detail: its status, dedupe key, timing, and the per-node timeline (each node's status, output item counts, duration, attempts, and any error).

```bash
bunx struere workflows run <run-id>
bunx struere workflows run <run-id> --env production
bunx struere workflows run <run-id> --verbose
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |
| `-v, --verbose` | Show full error messages (otherwise truncated) |

### workflows logs

List recent execution history, optionally for a single workflow. A lighter view than `runs` for scanning what fired and when.

```bash
bunx struere workflows logs
bunx struere workflows logs vip-payment --limit 25
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--limit <n>` | Maximum results. Default: `10` |
| `--json` | Output results as JSON |
| `-v, --verbose` | Show full error messages |

### workflows log

View a detailed execution log — by run/event ID, or by workflow slug (which resolves to the most recent execution). Shows the per-node timeline and the trigger payload.

```bash
bunx struere workflows log <run-id>
bunx struere workflows log vip-payment
bunx struere workflows log vip-payment --nth 2 --verbose
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--nth <n>` | When given a slug, show the nth most recent execution. Default: `1` (most recent) |
| `--json` | Output results as JSON |
| `-v, --verbose` | Show full error messages |

If `<identifier>` looks like a Convex ID it is treated as a run ID; otherwise it is treated as a workflow slug and resolved to its `--nth` most recent execution.

### workflows stats

Show run counts grouped by status for an environment.

```bash
bunx struere workflows stats
bunx struere workflows stats --env production --json
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |

Prints a per-status breakdown (`pending`, `running`, `completed`, `completed_with_errors`, `failed`, `dead`) and a total.

### workflows fire

Manually fire a workflow. This starts a **real run** — there is no dry-run. Safety comes from environment isolation: firing in `development`/`eval` resolves dev/eval connections and data, never production.

```bash
bunx struere workflows fire vip-payment
bunx struere workflows fire vip-payment --data '{"entityId": "ent_123"}'
bunx struere workflows fire vip-payment --env production --confirm
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--data <json>` | JSON payload for the trigger item |
| `--json` | Output results as JSON |
| `--confirm` | Skip the production confirmation prompt |

On success it prints the workflow, environment, run ID, and status, and suggests `struere workflows run <run-id>` to inspect the run as it advances. Firing in `production` prompts for confirmation unless `--confirm` is set.

### workflows enable

Enable a workflow so it fires on its trigger. For cron workflows, this schedules the next run.

```bash
bunx struere workflows enable vip-payment
bunx struere workflows enable vip-payment --env production --confirm
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |
| `--confirm` | Skip the production confirmation prompt |

### workflows disable

Disable a workflow so it stops firing. For cron workflows, this clears the next scheduled run.

```bash
bunx struere workflows disable vip-payment
bunx struere workflows disable vip-payment --env production --confirm
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |
| `--confirm` | Skip the production confirmation prompt |

### workflows cancel

Cancel a `pending` or `running` run, marking it `dead`.

```bash
bunx struere workflows cancel <run-id>
bunx struere workflows cancel <run-id> --env production --confirm
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |
| `--confirm` | Skip the production confirmation prompt |

### workflows retry

Retry a `failed` or `dead` run. Retry is branch-scoped: it resumes at the dead node, leaving already-completed branches untouched (their side effects are idempotency-guarded, so they are never repeated).

```bash
bunx struere workflows retry <run-id>
bunx struere workflows retry <run-id> --env production --confirm
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment: `development`, `production`, or `eval`. Default: `development` |
| `--json` | Output results as JSON |
| `--confirm` | Skip the production confirmation prompt |

### workflows import-trigger

Generate a workflow file from a legacy [linear automation](/platform/triggers). Reads the automation, converts it to a `defineWorkflow` builder file at `workflows/<slug>.ts`, and leaves the source automation intact (disable it separately when ready).

```bash
bunx struere workflows import-trigger notify-payment-received
bunx struere workflows import-trigger notify-payment-received --force
```

| Flag | Description |
|------|-------------|
| `--env <environment>` | Environment to read the automation from. Default: `development` |
| `--force` | Overwrite an existing workflow file |
| `--json` | Output results as JSON |

After importing, review the generated file and run `struere sync`. The conversion maps each automation action to a `.tool(...)` (or `.agent(...)`) call and rewrites `{{steps.<as>.x}}` references to `{{ $node["<as>"].json.x }}` and `{{trigger.data.x}}` to `{{ $trigger.data.x }}`.

## Examples

```bash
# See what's failing in production
bunx struere workflows list --failed --env production

# Inspect the most recent run of a workflow, with full errors
bunx struere workflows log vip-payment --verbose

# Test a workflow in development against dev data
bunx struere workflows fire vip-payment --data '{"entityId": "ent_123"}'

# Re-run a dead run's failed branch
bunx struere workflows retry m57abc123

# Migrate a linear automation to a workflow file
bunx struere workflows import-trigger notify-payment-received
bunx struere sync
```

## Authentication

The `workflows` commands work with both authentication methods:

| Method | How it works |
|--------|-------------|
| **API key** (`STRUERE_API_KEY`) | Environment is determined by the API key |
| **Clerk session** (`struere login`) | Uses your logged-in credentials |

Production-affecting subcommands (`fire`, `enable`, `disable`, `cancel`, `retry`) prompt for confirmation in `production` unless `--confirm` is passed.