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

# Workflows

> List, inspect, create, and update workflows and their nodes.

> [!NOTE]
>
> Workflow write commands are now available, but full support for the [Workflow API](https://loops.so/docs/api-reference/examples/workflows.md) is still evolving. Endpoints are in alpha and are subject to change.

The `workflows` command lets you list, inspect, create, and update workflows and their nodes in your Loops account.

## `list`

List workflows.

```bash theme={"dark"}
loops workflows list
```

Pass `--pick` to filter the list interactively with [fzf](https://github.com/junegunn/fzf) and copy the selected workflow ID to your clipboard. Requires `fzf` to be installed and on your `PATH`.

```bash theme={"dark"}
loops workflows list --pick
```

### Flags

| Flag | Description |
| - | - |
| `--pick` | Interactively pick a workflow and copy its ID to the clipboard. Requires [fzf](https://github.com/junegunn/fzf). |
| `--per-page` | Results per page (10–50, default 20) |
| `--cursor` | Pagination cursor for a specific page |

## `get`

Get a workflow by ID. Returns workflow metadata and a summary table of its nodes. For full node configuration, use [`workflows nodes get`](#nodes-get).

```bash theme={"dark"}
loops workflows get cls5d9u1w009yl70c7d8e9f0g
```

The output includes a `url` field with the workflow's address in the Loops app. Every command that prints a workflow includes it.

Pass `--web` to open the workflow in the Loops web app instead of printing its details.

```bash theme={"dark"}
loops workflows get cls5d9u1w009yl70c7d8e9f0g --web
```

### Flags

| Flag | Short | Description |
| - | - | - |
| `--web` | `-w` | Open in the Loops web app instead of printing details |

## `view`

Open a workflow in the Loops web app. Equivalent to [`get --web`](#get).

```bash theme={"dark"}
loops workflows view cls5d9u1w009yl70c7d8e9f0g
```

## Optimistic concurrency

Workflow write commands that modify an existing workflow accept an `--expected-revision-id` flag to guard against overwriting concurrent changes. Pass the revision ID from a prior [`workflows get`](#get); if the workflow has changed since then, the request is rejected with a conflict.

## `create`

Create a workflow.

```
loops workflows create --name <name> [--flags]
```

```bash theme={"dark"}
loops workflows create \
  --name "Welcome series" \
  --description "Onboarding emails for new signups"
```

### Flags

| Flag | Short | Description |
| - | - | - |
| `--name` | `-n` | Workflow name Required |
| `--description` | `-d` | Workflow description |
| `--mailing-list-id` | | Mailing list ID to send the workflow to. |

## `update`

Update a workflow's name and/or description.

```
loops workflows update <workflow-id> [--flags]
```

```bash theme={"dark"}
loops workflows update cls5d9u1w009yl70c7d8e9f0g \
  --name "Welcome series v2" \
  --expected-revision-id clv8g2x4z012yl70n5o6p7q8r
```

### Flags

| Flag | Short | Description |
| - | - | - |
| `--name` | `-n` | Workflow name |
| `--description` | `-d` | Workflow description |
| `--expected-revision-id` | | Expected workflow revision ID for [optimistic concurrency](#optimistic-concurrency). |

## `change-mailing-list`

Change a workflow's mailing list.

```
loops workflows change-mailing-list <workflow-id> --mailing-list-id <mailing-list-id> [--flags]
```

```bash theme={"dark"}
loops workflows change-mailing-list cls5d9u1w009yl70c7d8e9f0g \
  --mailing-list-id clw9h3y5a013yl70o6p7q8r9s
```

Preview the impact on queued contacts before applying the change with `--dry-run`.

### Flags

| Flag | Description |
| - | - |
| `--mailing-list-id` | Mailing list ID. Pass `"null"` to clear. Required |
| `--dry-run` | Report queued-contact impact without applying the change. |
| `--queued-contact-policy` | How to treat queued contacts: `fail` or `discard`. |
| `--expected-revision-id` | Expected workflow revision ID for [optimistic concurrency](#optimistic-concurrency). |

## `delete`

Delete a workflow. Deleted workflows are reported as not found by the other workflow commands.

```
loops workflows delete <workflow-id> [--flags]
```

```bash theme={"dark"}
loops workflows delete cls5d9u1w009yl70c7d8e9f0g
```

A workflow that is sending or has queued contacts is not deleted on the first attempt. Re-run the command with `--confirm` to delete the workflow, stop sending, and cancel its queued contacts.

```bash theme={"dark"}
loops workflows delete cls5d9u1w009yl70c7d8e9f0g --confirm
```

### Flags

| Flag | Description |
| - | - |
| `--confirm` | Delete a workflow that is sending or has queued contacts. |
| `--expected-revision-id` | Expected workflow revision ID for [optimistic concurrency](#optimistic-concurrency). |

## `nodes get`

Get full details for a single workflow node. See [Get workflow node](https://loops.so/docs/api-reference/get-workflow-node.md) for the full response schema.

```bash theme={"dark"}
loops workflows nodes get <workflow-id> <node-id>
loops workflows nodes get cls5d9u1w009yl70c7d8e9f0g clt6e0v2x010yl70h1i2j3k4l
```

For complex node configuration (such as audience filters or event property queries), use `--output json`.

## `nodes create`

Create a workflow node.

```
loops workflows nodes create <workflow-id> --insert-mode <mode> --node-type <type> [--flags]
```

```bash theme={"dark"}
loops workflows nodes create cls5d9u1w009yl70c7d8e9f0g \
  --insert-mode before \
  --node-type SendEmailAction \
  --to-node-id clt6e0v2x010yl70h1i2j3k4l
```

Choose where the node is inserted with `--insert-mode`:

* `between` — insert between two existing nodes, using `--from-node-id` and `--to-node-id`.
* `before` — insert ahead of a node, using `--to-node-id`.
* `after` — insert after `--from-node-id`. The source node must have exactly one outgoing connection.

### Flags

| Flag | Description |
| - | - |
| `--insert-mode` | Insert mode: `between`, `before`, or `after`. Required |
| `--node-type` | Node type: `AudienceFilter`, `BranchNode`, `ExperimentBranchNode`, `TimerAction`, `SendEmailAction`, or `VariantNode`. Required |
| `--from-node-id` | Source node ID (insert-mode `between` or `after`). |
| `--to-node-id` | Target node ID (insert-mode `between` or `before`). |
| `--expected-revision-id` | Expected workflow revision ID for [optimistic concurrency](#optimistic-concurrency). |

## `nodes update`

Update a workflow node.

```
loops workflows nodes update <workflow-id> <node-id> --payload-file <path> [--flags]
```

```bash theme={"dark"}
loops workflows nodes update cls5d9u1w009yl70c7d8e9f0g clt6e0v2x010yl70h1i2j3k4l \
  --payload-file ./node.json \
  --expected-revision-id clv8g2x4z012yl70n5o6p7q8r
```

The payload file must contain a `typeName` field identifying the node type:

```json theme={"dark"}
{
  "typeName": "TimerAction"
}
```

See [Get workflow node](https://loops.so/docs/api-reference/get-workflow-node.md) for the full node schema.

### Flags

| Flag | Description |
| - | - |
| `--payload-file` | Path to a JSON file with the node payload (must include a `typeName` field). Required |
| `--expected-revision-id` | Expected workflow revision ID for [optimistic concurrency](#optimistic-concurrency). |

## `nodes delete`

Delete a workflow node.

```
loops workflows nodes delete <workflow-id> <node-id> [--flags]
```

```bash theme={"dark"}
loops workflows nodes delete cls5d9u1w009yl70c7d8e9f0g clt6e0v2x010yl70h1i2j3k4l \
  --recursive
```

Preview the impact on queued contacts before applying the deletion with `--dry-run`.

### Flags

| Flag | Description |
| - | - |
| `--recursive` | Also delete downstream nodes. |
| `--dry-run` | Report queued-contact impact without applying the deletion. |
| `--queued-contact-policy` | How to treat queued contacts: `fail` or `discard`. |
| `--expected-revision-id` | Expected workflow revision ID for [optimistic concurrency](#optimistic-concurrency). |

## `nodes add-branch`

Add a branch to a branch node.

```
loops workflows nodes add-branch <workflow-id> <node-id> [--flags]
```

```bash theme={"dark"}
loops workflows nodes add-branch cls5d9u1w009yl70c7d8e9f0g clt6e0v2x010yl70h1i2j3k4l
```

### Flags

| Flag | Description |
| - | - |
| `--expected-revision-id` | Expected workflow revision ID for [optimistic concurrency](#optimistic-concurrency). |

## `nodes reroute`

Move a node's single outgoing connection to a new target. The source node must have exactly one outgoing connection.

```
loops workflows nodes reroute <workflow-id> <node-id> --new-target-node-id <node-id> [--flags]
```

```bash theme={"dark"}
loops workflows nodes reroute cls5d9u1w009yl70c7d8e9f0g clt6e0v2x010yl70h1i2j3k4l \
  --new-target-node-id clw9h3y5a013yl70o6p7q8r9s
```

### Flags

| Flag | Description |
| - | - |
| `--new-target-node-id` | Node ID that should receive the source node's outgoing connection. Required |
| `--expected-revision-id` | Expected workflow revision ID for [optimistic concurrency](#optimistic-concurrency). |


## Related topics

- [Workflows](https://loops.so/docs/workflows.md)
- [Pausing workflows](https://loops.so/docs/workflows/pausing.md)
- [Delete a workflow](https://loops.so/docs/api-reference/delete-workflow.md)
- [Create a workflow](https://loops.so/docs/api-reference/create-workflow.md)
- [List workflows](https://loops.so/docs/api-reference/list-workflows.md)