> ## 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 layout:apply

> Apply a forest-layout.json file to an environment and team

# forest layout:apply

Apply a `forest-layout.json` file, produced by [`forest layout:pull`](https://docs.forest.app/reference/cli/layout-pull), to an environment and team. The CLI compares the file with the target's current layout, shows the changes, and sends them as JSON Patch operations once you confirm.

## Usage

```bash theme={null}
forest layout:apply <FILE> [options]
```

## Arguments

| Argument | Description |
| - | - |
| `FILE` | Layout file to apply, such as `forest-layout.json` (required) |

## Options

| Option | Description |
| - | - |
| `-e, --env` | Environment to apply to, by name or ID. Prompted when omitted |
| `-t, --team` | Team to apply to, by name or ID. Prompted when omitted |
| `-p, --projectId` | The ID of the project. See [project selection](https://docs.forest.app/reference/cli/overview.md#project-selection) when omitted |
| `-f, --force` | Apply without asking for confirmation |
| `--with-workflows` | Also upload the workflow definitions (`workflows/<id>.bpmn`) next to the file to the target environment |

## How it works

1. The CLI reads the file and fetches the current layout of the target environment and team, for the sections present in the file.
2. It computes the difference and prints the plan.
3. If the target already matches the file, it stops with `Nothing to apply`.
4. Once you confirm, it sends one atomic patch per section, then uploads the workflow definitions that changed.

Applying the same file twice makes no change the second time.

> [!NOTE]
>
> The target is always the `--env` and `--team` you pass, or the ones you pick at the prompt. The environment recorded in the file header is never used as a default.

## Workflows across environments

Workflow definitions (BPMN) are stored per environment. A file pulled from another environment references definitions that do not exist on the target, and the CLI warns about it. Pull and apply with `--with-workflows` to carry the definitions along:

```bash theme={null}
forest layout:pull --env Development --with-workflows
forest layout:apply forest-layout.json --env Production --team Operations --with-workflows
```

## Examples

```bash theme={null}
# Promote the development layout of the Operations team to staging
forest layout:pull --env Development --team Operations
forest layout:apply forest-layout.json --env staging --team Operations

# Apply in a script, without the confirmation prompt
forest layout:apply forest-layout.json -e Production -t Operations --force
```


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