> ## 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](/guides/admin-guide/workflows) 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](/guides/community-and-resources/support-and-help/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](/guides/admin-guide/workflows/create-a-new-workflow) and the [workflow file reference](/guides/admin-guide/workflows/workflow-file-reference).

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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](/guides/admin-guide/workflows/workflow-partial-deployment) options.

## Create a workflow environment from scratch

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](/guides/community-and-resources/support-and-help/env-zero-cli/command-reference) - Every CLI command and flag.
* [Workflow file reference](/guides/admin-guide/workflows/workflow-file-reference) - All `env0.workflow.yml` settings.
* [Workflow variables](/guides/admin-guide/variables/workflow-variables) - Pass variables to sub-environments.


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