> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/warpdotdev/warp/llms.txt
> Use this file to discover all available pages before exploring further.

# oz environment — create and manage cloud environments

> Create, list, update, and delete Warp cloud environments. Environments define the container image, repos, and setup commands used by cloud agents.

Cloud environments define the isolated containers that Warp agents run in when you use `oz agent run-cloud`. An environment pins a Docker base image, specifies which Git repositories to clone, and configures setup commands that run after the repos are cloned. Reusing the same environment across many agent runs keeps your agents consistent and avoids repeating setup work.

## Synopsis

```bash theme={null}
oz environment <subcommand> [flags]
```

**Alias:** `oz e`

## Subcommands

| Subcommand    | Description                           |
| ------------- | ------------------------------------- |
| `list`        | List all cloud environments           |
| `get <id>`    | Get details of a specific environment |
| `create`      | Create a new cloud environment        |
| `update <id>` | Update an existing environment        |
| `delete <id>` | Delete a cloud environment            |
| `image list`  | List available Warp dev base images   |

***

## oz environment list

Lists all cloud environments available to your account.

```bash theme={null}
oz environment list
```

### Examples

```bash theme={null}
oz environment list
oz environment list --output-format json
```

***

## oz environment get

Retrieves details of a specific environment by its ID.

```bash theme={null}
oz environment get <id>
```

### Arguments

| Argument | Description                       |
| -------- | --------------------------------- |
| `id`     | ID of the environment to retrieve |

### Examples

```bash theme={null}
oz environment get env_abc123
```

***

## oz environment create

Creates a new cloud environment.

```bash theme={null}
oz environment create --name <name> [flags]
```

### Flags

<ParamField path="--name" type="string" required>
  Name of the environment.

  Short form: `-n`
</ParamField>

<ParamField path="--description" type="string">
  Description of the environment. Maximum 240 characters.
</ParamField>

<ParamField path="--docker-image" type="string">
  Docker image to use as the base for this environment. Run `oz environment image list` to see suggested Warp dev images. If not specified, you will be prompted to select from available images interactively.

  Short form: `-d`
</ParamField>

<ParamField path="--repo" type="string">
  Git repository to clone into the environment, in `owner/repo` format. Repeatable — specify multiple times to clone multiple repositories.

  Short form: `-r`
</ParamField>

<ParamField path="--setup-command" type="string">
  Command to run after the repositories are cloned. Repeatable — specify multiple times to add multiple setup steps.

  Short form: `-c`
</ParamField>

### Examples

```bash theme={null}
# Create a minimal environment
oz environment create --name "my-app"

# Create an environment with a specific image and repo
oz environment create \
  --name "my-app" \
  --docker-image warp/dev:node20 \
  --repo owner/my-app

# Create an environment with setup commands
oz environment create \
  --name "my-app" \
  --docker-image warp/dev:node20 \
  --repo owner/my-app \
  --setup-command "npm install" \
  --setup-command "npm run build"

# Create with a description
oz environment create \
  --name "api-server" \
  --description "Node.js API server with PostgreSQL" \
  --repo owner/api-server \
  --setup-command "npm install"
```

***

## oz environment update

Updates an existing cloud environment. Only the fields you specify are changed; everything else is left as-is.

```bash theme={null}
oz environment update <id> [flags]
```

### Arguments

| Argument | Description                     |
| -------- | ------------------------------- |
| `id`     | ID of the environment to update |

### Flags

<ParamField path="--name" type="string">
  New name for the environment.

  Short form: `-n`
</ParamField>

<ParamField path="--description" type="string">
  New description (max 240 characters). Cannot be combined with `--remove-description`.
</ParamField>

<ParamField path="--remove-description" type="boolean">
  Remove the description from the environment. Cannot be combined with `--description`.
</ParamField>

<ParamField path="--docker-image" type="string">
  New Docker base image.

  Short form: `-d`
</ParamField>

<ParamField path="--repo" type="string">
  Git repository to add, in `owner/repo` format. Repeatable.

  Short form: `-r`
</ParamField>

<ParamField path="--remove-repo" type="string">
  Git repository to remove, in `owner/repo` format. Repeatable.
</ParamField>

<ParamField path="--setup-command" type="string">
  Setup command to append to the list. Repeatable.

  Short form: `-c`
</ParamField>

<ParamField path="--remove-setup-command" type="string">
  Setup command to remove from the list. Repeatable.
</ParamField>

<ParamField path="--force" type="boolean">
  Force the update without checking for integration usage.
</ParamField>

### Examples

```bash theme={null}
# Rename an environment
oz environment update env_abc123 --name "new-name"

# Add a repository to an existing environment
oz environment update env_abc123 --repo owner/another-repo

# Replace the Docker image
oz environment update env_abc123 --docker-image warp/dev:python311

# Remove a setup command
oz environment update env_abc123 --remove-setup-command "npm run build"

# Remove a repository
oz environment update env_abc123 --remove-repo owner/old-repo
```

***

## oz environment delete

Deletes a cloud environment.

```bash theme={null}
oz environment delete <id> [flags]
```

### Arguments

| Argument | Description                     |
| -------- | ------------------------------- |
| `id`     | ID of the environment to delete |

### Flags

<ParamField path="--force" type="boolean">
  Delete without checking for integration usage.
</ParamField>

### Examples

```bash theme={null}
oz environment delete env_abc123
oz environment delete env_abc123 --force
```

***

## oz environment image list

Lists available Warp dev base images from Docker Hub. Use the image names returned here as the value for `--docker-image` when creating or updating an environment.

```bash theme={null}
oz environment image list
```

### Examples

```bash theme={null}
oz environment image list
oz environment image list --output-format json
```