> ## 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:pull

> Download the layout of an environment and team into a forest-layout.json file

# forest layout:pull

Pull the layout of an environment, for one team, into a `forest-layout.json` file. The file captures the collection display settings, the sidebar folders and the workflows. Version it in Git, review it, and apply it to another environment with [`forest layout:apply`](https://docs.forest.app/reference/cli/layout-apply).

## Usage

```bash theme={null}
forest layout:pull [options]
```

## Options

| Option | Description |
| - | - |
| `-e, --env` | Environment to pull from, by name or ID. Prompted when omitted |
| `-t, --team` | Team whose layout to pull, 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 |
| `-o, --out` | Output file path. Default: `forest-layout.json` |
| `--with-workflows` | Also download the BPMN definition of each workflow into `workflows/<id>.bpmn`, next to the output file |

## The layout file

The file starts with a `forest` header recording where it was pulled from (project, environment, team, date), followed by one section per layout domain:

| Section | Content |
| - | - |
| `layout` | Collections: display names, columns, fields, segments, actions, summary views, charts |
| `folders` | The sidebar folders and their content |
| `workflows` | The workflows attached to collections |

The header is informational: [`forest layout:apply`](https://docs.forest.app/reference/cli/layout-apply) never targets the environment the file came from by default.

## Workflow definitions

A workflow's behavior lives in a BPMN file stored per environment, and the layout file only references it. To move workflows to another environment, pull with `--with-workflows`: the CLI writes one `workflows/<id>.bpmn` file per workflow and removes the files of workflows that no longer exist. Then apply with `--with-workflows` on the target.

## Examples

```bash theme={null}
# Pick the environment and team interactively
forest layout:pull

# Pull the development layout of the Operations team
forest layout:pull --env Development --team Operations

# Pull the production layout of the Support team into a custom file
forest layout:pull --env Production --team Support --out layouts/support.json

# Pull the layout and the workflow definitions
forest layout:pull --env Production --with-workflows
```


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