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

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.

oz environment list

Examples

oz environment list
oz environment list --output-format json

---

oz environment get

Retrieves details of a specific environment by its ID.

oz environment get <id>

Arguments

Argument	Description
id	ID of the environment to retrieve

Examples

oz environment get env_abc123

---

oz environment create

Creates a new cloud environment.

oz environment create --name <name> [flags]

Flags

--name · string · required

Name of the environment.

Short form: -n

--description · string

Description of the environment. Maximum 240 characters.

--docker-image · 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

--repo · string

Git repository to clone into the environment, in owner/repo format. Repeatable — specify multiple times to clone multiple repositories.

Short form: -r

--setup-command · string

Command to run after the repositories are cloned. Repeatable — specify multiple times to add multiple setup steps.

Short form: -c

Examples

# 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.

oz environment update <id> [flags]

Arguments

Argument	Description
id	ID of the environment to update

Flags

--name · string

New name for the environment.

Short form: -n

--description · string

New description (max 240 characters). Cannot be combined with --remove-description.

--remove-description · boolean

Remove the description from the environment. Cannot be combined with --description.

--docker-image · string

New Docker base image.

Short form: -d

--repo · string

Git repository to add, in owner/repo format. Repeatable.

Short form: -r

--remove-repo · string

Git repository to remove, in owner/repo format. Repeatable.

--setup-command · string

Setup command to append to the list. Repeatable.

Short form: -c

--remove-setup-command · string

Setup command to remove from the list. Repeatable.

--force · boolean

Force the update without checking for integration usage.

Examples

# 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.

oz environment delete <id> [flags]

Arguments

Argument	Description
id	ID of the environment to delete

Flags

--force · boolean

Delete without checking for integration usage.

Examples

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.

oz environment image list

Examples

oz environment image list
oz environment image list --output-format json