--- title: "alis environment" url: "https://docs.alisx.com/reference/cli/environment/" --- # alis environment Manage a product's deployment environments: list them, create one, designate deploy branches, and read, set or unset environment variables. ## Synopsis ```bash alis environment branches [..] [flags] alis environment list [.] [flags] alis environment new [.] --display-name [--region ] [--production] [flags] alis environment refresh .. --output [flags] alis environment rename [..] --display-name [flags] alis environment set [..] NAME=VALUE [NAME=VALUE ...] [flags] alis environment unset [..] NAME [NAME ...] [flags] alis environment variables [.] [flags] ``` Aliases: `environment`, `env`, `envs`, `environments`. ## Description A deployment environment is a deployment target inside a product with its own Google Cloud project. Deployment environment ids come from `alis context view --json` or `alis environment list`; never guess them. Changing or revealing a production deployment environment's variables is gated like a production deploy. ## Subcommands ### alis environment branches View or designate the git branches a deployment environment is meant to be deployed from. With `--allow` the designation is replaced by the given branches; with `--clear` it is removed; without either, the current designation is printed. When branches are designated, the TUI and `alis deploy`/`alis build --deploy` ask for confirmation before deploying a version built from another branch. Deploys are warned about, never blocked outright. No deploy is triggered. ```bash alis environment branches [..] [flags] ``` | Flag | Type | Default | Meaning | |---|---|---|---| | `--allow ` | strings | | Branch to designate (repeatable; replaces the current designation). | | `--clear` | bool | false | Remove the designation so any branch may deploy. | | `--yes` | bool | false | Skip the approval prompt (same as `--approve`). | ### alis environment list List deployment environments without environment variable values. ```bash alis environment list [.] [flags] ``` No flags beyond the global flags. `--json` returns `environments[]` with `id`, `displayName`, `production`, `status` and `allowedBranches`. ### alis environment new Create a new deployment environment in a product. The deployment environment's Google Cloud project is created in `--region`; without it the product's region is used. The new deployment environment's id is shown by `alis context view .`. ```bash alis environment new [.] --display-name [--region ] [--production] [flags] ``` | Flag | Type | Default | Meaning | |---|---|---|---| | `--display-name ` | string | | Human-readable deployment environment name (required). | | `--production` | bool | false | Mark as a production deployment environment. | | `--region ` | string | the product's region | Google Cloud region for the deployment environment's project, for example `africa-south1`. | ### alis environment refresh Generate the `.env` file for a deployment environment. `--output` writes it with owner-only permissions and prints only the path and the variable names; use it to populate `/.alis/.env`, which `alis run` loads. The `.env` holds secret values, so printing it to stdout needs `--reveal`, which asks for approval (a production deployment environment also needs `--confirm-production`). Service account key bytes are never printed; `--key-path` writes them to a file. ```bash alis environment refresh .. --output [flags] ``` | Flag | Type | Default | Meaning | |---|---|---|---| | `--confirm-production` | bool | false | Confirm printing a production deployment environment's `.env`. | | `--key-path ` | string | | Path the service account key is written to (sets `GOOGLE_APPLICATION_CREDENTIALS` in the `.env`). | | `-o`, `--output ` | string | | Write the `.env` to this file (owner-only) and print only the variable names. | | `--reveal` | bool | false | Print the `.env` contents to stdout (asks for approval; production also needs `--confirm-production`). | ### alis environment rename Rename the customer-facing display label of a deployment environment. The stable id, deployment references and cloud resources do not change, and no Terraform deploy is triggered. ```bash alis environment rename [..] --display-name [flags] ``` | Flag | Type | Default | Meaning | |---|---|---|---| | `--display-name ` | string | | New customer-facing deployment environment name (required). | | `--yes` | bool | false | Skip the approval prompt (same as `--approve`). | ### alis environment set Add or update environment variables. Names use `UPPER_SNAKE_CASE`; a value may contain `=` (quote it in your shell). The reference may be omitted inside a product directory when the first argument contains `=`. `--secret` stores the value in the deployment environment's Google Cloud Secret Manager (secret id = the variable name) instead of in Alis. Such a variable is left out of deployments, Terraform reads the secret directly, and its value is never returned, so `alis environment variables` shows it as `(Secret Manager)`. Setting a secret-backed variable again without `--secret` writes a new secret version; `--secret=false` with a value moves it back into Alis. Variables flow into `alis environment refresh` immediately. Deployed services only pick them up at their next deploy; `--deploy` triggers a deployment environment deploy now. Writing requires the deployment environment admin role. Concurrent edits follow last-writer-wins. ```bash alis environment set [..] NAME=VALUE [NAME=VALUE ...] [flags] ``` | Flag | Type | Default | Meaning | |---|---|---|---| | `--confirm-production` | bool | false | Confirm applying to a production deployment environment. | | `--deploy` | bool | false | Also trigger a deployment environment deploy. | | `--secret` | bool | false | Store the value in Secret Manager instead of in Alis. | | `--yes` | bool | false | Skip the approval prompt (same as `--approve`). | ### alis environment unset Remove environment variables. Removing a name that is not set is a no-op, reported under `notFound`. Pass the deployment environment reference first, then the names. ```bash alis environment unset [..] NAME [NAME ...] [flags] ``` | Flag | Type | Default | Meaning | |---|---|---|---| | `--confirm-production` | bool | false | Confirm applying to a production deployment environment. | | `--deploy` | bool | false | Also trigger a deployment environment deploy. | | `--yes` | bool | false | Skip the confirmation prompt (same as `--approve`). | ### alis environment variables List the environment variables of every deployment environment in a product. Values are masked: text shows `••••••••` (or `(empty)`), and `--json` gives `{name, set}` per variable. `--reveal` prints plaintext values; it asks for approval, and a production deployment environment also needs `--confirm-production`. Narrow what is revealed with `-e` and `--name`. ```bash alis environment variables [.] [flags] ``` Aliases: `variables`, `vars`. | Flag | Type | Default | Meaning | |---|---|---|---| | `--confirm-production` | bool | false | Confirm revealing a production deployment environment's values. | | `-e`, `--environment ` | string | | Only this deployment environment (ids from `alis context view`). | | `--name ` | strings | | Only this variable (repeatable). | | `--reveal` | bool | false | Print plaintext values (asks for approval; production also needs `--confirm-production`). | ## Examples ```bash title="Terminal" alis environment list acme.shop --json alis environment new acme.shop --display-name "Staging" --json alis environment refresh acme.shop. --output ~/alis.build/acme/build/shop/.alis/.env alis environment set acme.shop. FEATURE_FLAG=on --json alis environment set acme.shop. API_KEY=… --secret --deploy --json alis environment unset acme.shop. FEATURE_FLAG --json alis environment variables acme.shop --json alis environment branches acme.shop. --allow main --json ``` ## Exit codes `set`, `unset`, `refresh --reveal` and `variables --reveal` on a production deployment environment exit 3 with `PRODUCTION_CONFIRMATION_REQUIRED` until `--confirm-production` is passed. `set` is mutating-class and `unset` and `--reveal` are destructive-class under the automation tiers. See [Exit codes](https://docs.alisx.com/reference/cli/exit-codes.md).