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

# Deploy workflows with the env zero CLI

> Deploy env zero workflows from the CLI with a manifest for per-sub-environment branches and variables, or deploy and destroy a single sub-environment.

A [workflow](https://docs.envzero.com/guides/admin-guide/workflows.md) 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](https://docs.envzero.com/guides/community-and-resources/support-and-help/env-zero-cli.md), 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](https://docs.envzero.com/guides/admin-guide/workflows/create-a-new-workflow.md) and the [workflow file reference](https://docs.envzero.com/guides/admin-guide/workflows/workflow-file-reference.md).

## Deploy with per-sub-environment branches and variables

**1. Write a manifest**

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

```yaml deploy.yaml theme={null}
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.

**2. Deploy**

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

```bash theme={null}
env0 environment deploy <workflow-environment-id> --manifest deploy.yaml --wait
```

```bash theme={null}
env0 environment create --name <name> --project <project-id> --template <workflow-template-id> --manifest deploy.yaml --wait
```

**3. Verify each sub-environment's branch**

```bash theme={null}
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](https://docs.envzero.com/guides/admin-guide/workflows/workflow-partial-deployment.md) options.

## Create a workflow environment from scratch

**1. 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.

```bash theme={null}
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`.

**2. Create the workflow template**

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

```bash theme={null}
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.

**3. Create the environment**

```bash theme={null}
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

* [Set default variables for sub-environments](https://docs.envzero.com/guides/admin-guide/variables/workflow-variables.md) at the template level
* [Look up every CLI command and flag](https://docs.envzero.com/guides/community-and-resources/support-and-help/env-zero-cli/command-reference.md), including `--manifest` and `--node`


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