Deploy workflows with the env zero CLI

A workflow environment is made of sub-environments, each defined under environments: in the repository’s env0.workflow.yml. From the CLI you can:

Deploy the whole workflow with a different branch and variables for each sub-environment, using a manifest file.
Deploy or destroy a single sub-environment, or run the workflow from one sub-environment onward.

Both identify sub-environments by alias: the key of each block under environments: in env0.workflow.yml, not its templateName.

Prerequisites

The env zero CLI, signed in or with API key environment variables set
A workflow template whose env0.workflow.yml defines the sub-environments. See Create a new workflow and the workflow file reference.

Deploy with per-sub-environment branches and variables

Write a manifest

The manifest is a YAML or JSON file. Every field is optional.

deploy.yaml

revision: main
variables:
  - name: DISABLE_PAYMENTS
    value: "true"
  - name: API_TOKEN
    value: <API_TOKEN>
    sensitive: true
  - name: region
    value: us-east-1
    type: terraform
subEnvironments:
  api:
    revision: feat/new-auth
    variables:
      - name: LOG_LEVEL
        value: debug
  worker:
    revision: feat/queue
    requiresApproval: true

Field	Description
`revision`	Branch or tag for the workflow
`variables`	Workflow-level variables
`subEnvironments.<alias>.revision`	Branch or tag for that sub-environment
`subEnvironments.<alias>.variables`	Variables for that sub-environment
`subEnvironments.<alias>.requiresApproval`	Require approval for that sub-environment

Each variable takes name and value. type is environment (default) or terraform. sensitive defaults to false. Unknown fields are rejected.

Deploy

Pass the manifest to environment deploy for an existing workflow environment, or to environment create --template for a new one:

env0 environment deploy <workflow-environment-id> --manifest deploy.yaml --wait

env0 environment create --name <name> --project <project-id> --template <workflow-template-id> --manifest deploy.yaml --wait

Verify each sub-environment's branch

env0 context <workflow-environment-id> -o compact | jq '.data.subEnvironments'

Each entry shows the sub-environment’s alias, plus the blueprintRevision and status of its latest deployment.

How the manifest combines with flags

Workflow-level variables merge with --var, --secret, and --tf-var. A flag wins over the manifest for the same variable name and type.
--revision wins over the manifest’s revision.
Per-sub-environment values come only from the manifest.
--manifest cannot be combined with --repository.

Turn sub-environments on and off

The manifest has no per-sub-environment disabled field. Toggle a sub-environment with a workflow-level variable that env0.workflow.yml reads, for example disabled: ${DISABLE_PAYMENTS}, and set that variable under the manifest’s top-level variables.

Alias checks

The workflow ignores an override for an alias it does not recognize, so the CLI checks aliases first. A wrong alias exits 64 and lists the valid ones.

On deploy, the check runs before anything is sent. Nothing is deployed.
On create, the environment does not exist yet. The CLI creates it, then waits up to about 30 seconds for the workflow to resolve and checks the aliases. A wrong alias fails after the environment exists, so destroy it and create it again with a fixed manifest. If the workflow does not resolve in time, create exits 0 and the next deploy checks the aliases.

deploy --manifest checks aliases against the last resolved workflow file. If the environment’s only deployment failed before the workflow resolved, deploy once without --manifest first.

Deploy or destroy part of a workflow

Pass --node <alias> with the workflow environment’s id:

Goal	Command
Deploy one sub-environment	`env0 environment deploy <workflow-environment-id> --node <alias>`
Deploy one sub-environment and everything that depends on it, in order	`env0 environment deploy <workflow-environment-id> --node <alias> --run-from-here`
Destroy one sub-environment, keeping the rest of the workflow	`env0 environment destroy <workflow-environment-id> --node <alias> --yes`

The result is one deployment on the workflow environment. --wait exits with its final status.
A wrong alias exits 64, and nothing is sent.
The workflow’s revision is fixed: --node cannot be combined with --revision or a manifest revision. Per-sub-environment manifest values still apply to the sub-environments that run.
destroy --node does not accept --skip-state-refresh, --checkout-updated-code, or --requires-approval.
To bring back a destroyed sub-environment, run deploy --node <alias>.

These match the UI’s partial workflow deployment options.

Create a workflow environment from scratch

Create a template for each sub-environment

Each sub-environment in env0.workflow.yml that uses templateName needs a Terraform, OpenTofu, Terragrunt, or other non-workflow template. A sub-environment cannot point to another workflow template.

env0 template create --name my-api --repository https://github.com/<org>/<repo> --path api --type terraform

For a private repository, add --vcs-connection-id with an id from env0 vcs list.

Create the workflow template

Point --path at the directory that holds env0.workflow.yml:

env0 template create --name my-workflow --repository https://github.com/<org>/<repo> --path workflow --type workflow

template create assigns the template to your stored project, or to --project. environment create only deploys templates assigned to the target project.

Create the environment

env0 environment create --name my-workflow --project <project-id> --template <workflow-template-id> --wait

Add --manifest to set per-sub-environment branches and variables on the first deployment.

When a workflow deployment fails, deployment get, deployment logs, and context show the reason in errorMessage, for example Nested workflows are not allowed.

Next steps

Command reference - Every CLI command and flag.
Workflow file reference - All env0.workflow.yml settings.
Workflow variables - Pass variables to sub-environments.

GET STARTED

ENVIRONMENTS & DEPLOYMENTS

TEMPLATES & IaC TOOLS

PLATFORM CONFIGURATION

SELF-HOSTED AGENTS

CLOUD MANAGEMENT

GOVERNANCE & POLICIES

ACCESS & IDENTITY

SECURITY & COMPLIANCE

INTEGRATIONS & DEVELOPER TOOLS

BILLING & SUPPORT

Deploy workflows with the env zero CLI

Prerequisites

Deploy with per-sub-environment branches and variables

How the manifest combines with flags

Turn sub-environments on and off

Alias checks

Deploy or destroy part of a workflow

Create a workflow environment from scratch

Next steps

​Prerequisites

​Deploy with per-sub-environment branches and variables

​How the manifest combines with flags

​Turn sub-environments on and off

​Alias checks

​Deploy or destroy part of a workflow

​Create a workflow environment from scratch

​Next steps

Prerequisites

Deploy with per-sub-environment branches and variables

How the manifest combines with flags

Turn sub-environments on and off

Alias checks

Deploy or destroy part of a workflow

Create a workflow environment from scratch

Next steps