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

# forest workflow:apply

> Create or update a workflow from a JSON steps specification

# forest workflow:apply

Create or update one workflow from a JSON specification of its steps. The CLI compiles the steps into a BPMN definition, uploads it to the target environment, and attaches the workflow to its collection. The rest of the layout is left untouched.

## Usage

```bash theme={null}
forest workflow:apply [FILE] [options]
```

## Arguments

| Argument | Description |
| - | - |
| `FILE` | JSON workflow specification. Use `-` or omit it to read from standard input |

## Options

| Option | Description |
| - | - |
| `-e, --env` | Environment, by name or ID. Prompted when omitted |
| `-t, --team` | Team, by name or ID. Prompted when omitted |
| `-p, --projectId` | The ID of the project |
| `-f, --force` | Apply without asking for confirmation |
| `--dry-run` | Resolve the target, match the workflow and print the plan, without sending anything |

When the specification comes from standard input, the CLI cannot prompt: pass `-p`, `-e`, `-t` and `--force`.

## Specification

| Field | Required | Description |
| - | - | - |
| `name` | Yes | Name of the workflow |
| `collection` | Yes | Name of the collection the workflow runs on |
| `steps` | Yes | Array of steps. Must contain at least one `end` step |
| `start` | No | ID of the first step. Defaults to the first step of `steps` |
| `segments` | No | IDs of the segments the workflow is available on. Omitting it means no segment |
| `id` | No | ID of an existing workflow to update. Must match a workflow of the environment |
| `position` | No | Position of the workflow in the list |
| `version` | No | Specification version. Only `1` is supported |

Each step has an `id` (letters, digits, `_` and `-`, starting with a letter or `_`), a `type`, and optionally a `title` and a `prompt` (the instruction shown for the step).

| Type | Step | Specific fields |
| - | - | - |
| `guidance` | Manual task for the operator | `next` |
| `read` | Read data | `next`, `auto`, `autoComplete` |
| `update` | Update data | `next`, `auto`, `autoComplete` |
| `action` | Trigger an action | `next`, `auto`, `autoComplete` |
| `load-related` | Load a related record | `next`, `auto`, `autoComplete` |
| `mcp` | Call an MCP server | `next`, `mcpServerId`, `auto`, `autoComplete` |
| `escalation` | Escalate to an inbox | `next`, `inboxId` (an existing inbox) |
| `condition` | Decision with several outcomes | `branches`: at least two `{ "answer", "next", "color"? }` |
| `end` | End of the workflow | none |

`auto` runs the step automatically and `autoComplete` completes it automatically.

## Create or update

The specification is the source of truth for the workflow:

* With an `id`, the CLI updates that workflow. An `id` that matches no workflow is an error, not a creation.
* Without an `id`, the CLI updates the workflow with the same `name` on the same `collection`, or creates one if none exists.
* To change a workflow, edit the specification and apply it again. The CLI recompiles the whole definition and uploads it only if it changed. Applying an unchanged specification reports `Nothing to apply`.

A workflow cannot move to another collection.

## Example

```json refund-review.json theme={null}
{
  "name": "Refund review",
  "collection": "refund_requests",
  "steps": [
    { "id": "review", "type": "guidance", "title": "Review request", "prompt": "Check the reason and the amount", "next": "decide" },
    { "id": "decide", "type": "condition", "title": "Approve?", "branches": [
      { "answer": "Approve", "next": "refund" },
      { "answer": "Reject", "next": "done" }
    ] },
    { "id": "refund", "type": "update", "title": "Mark refunded", "prompt": "Set the status to refunded", "next": "done" },
    { "id": "done", "type": "end", "title": "Done" }
  ]
}
```

```bash theme={null}
# Preview the plan
forest workflow:apply refund-review.json --env Development --team Operations --dry-run

# Create or update the workflow
forest workflow:apply refund-review.json --env Development --team Operations

# Read the specification from standard input
cat refund-review.json | forest workflow:apply - -p 42 -e Development -t Operations --force
```

> [!NOTE]
>
> The specification describes the shape of a workflow. Settings such as the fields of a `read` or `update` step, or the action of an `action` step, are not part of it yet: configure them in the workflow editor.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.