> ## 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](/docs/api-reference/examples/workflows) is still evolving. Endpoints are in alpha and are subject to change.
</Note>

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
```

## 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 <Badge color="red" size="sm">Required</Badge> |
| `--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. <Badge color="red" size="sm">Required</Badge> |
| `--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).   |

## `nodes get`

Get full details for a single workflow node. See [Get workflow node](/docs/api-reference/get-workflow-node) 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 \
  --before-node-id clt6e0v2x010yl70h1i2j3k4l
```

Use `--insert-mode between` with `--from-node-id` and `--to-node-id` to insert a node between two existing nodes, or `--insert-mode before` with `--before-node-id` to insert ahead of a node.

### Flags

| Flag                     | Description                                                                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--insert-mode`          | Insert mode: `between` or `before`. <Badge color="red" size="sm">Required</Badge>                                                                                    |
| `--node-type`            | Node type: `AudienceFilter`, `BranchNode`, `ExperimentBranchNode`, `TimerAction`, `SendEmailAction`, or `VariantNode`. <Badge color="red" size="sm">Required</Badge> |
| `--from-node-id`         | Source node ID (insert-mode `between`).                                                                                                                              |
| `--to-node-id`           | Target node ID (insert-mode `between`).                                                                                                                              |
| `--before-node-id`       | Node ID to insert before (insert-mode `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](/docs/api-reference/get-workflow-node) for the full node schema.

### Flags

| Flag                     | Description                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `--payload-file`         | Path to a JSON file with the node payload (must include a `typeName` field). <Badge color="red" size="sm">Required</Badge> |
| `--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). |


## Related topics

- [Workflows](/docs/workflows.md)
- [API Introduction](/docs/api-reference/intro.md)
- [Duplicating emails](/docs/creating-emails/duplicating-emails.md)
- [Pausing workflows](/docs/workflows/pausing.md)
- [Triggering workflows](/docs/workflows/triggers.md)