---
title: "Manage environment variables"
url: "https://docs.alisx.com/how-to/alis-build/manage-environment-variables/"
---
# Manage environment variables

Set the configuration your services read per deployment environment, keep secrets in Secret Manager, and get the same values onto your machine for local runs. Variables live on the deployment environment and reach your Terraform as input variables on the next deploy.

## Prerequisites

- The deployment environment admin role on the deployment environment, for writes. Builders can list names.
- Variable names in `UPPER_SNAKE_CASE`.

## List variables

```bash title="Terminal"
alis environment variables acme.sh
```

Every deployment environment in the product is listed with its variable names; values are masked. Narrow with `-e <env-id>` and `--name API_URL`. `--reveal` prints plaintext values after an approval prompt; on a production environment it also needs `--confirm-production`.

!!! danger "Revealed values land in the terminal"
    Anything `--reveal` prints ends up in your scroll-back and in any coding-agent transcript. Reveal one variable at a time and only when you need the value.

The console shows the same data on the product's **Variables** page, a matrix of every variable across deployment environments, and on each deployment environment's **Variables** page.

## Set and unset

=== "CLI"

    ```bash title="Terminal"
    alis environment set acme.sh.<env-id> API_URL=https://api.example.com RATE_LIMIT=100
    alis environment unset acme.sh.<env-id> RATE_LIMIT
    ```

    A value may contain `=`; quote it in your shell. Inside a product directory the reference can be omitted when the first argument contains `=`. Removing a name that is not set is a no-op, reported under `notFound`. Concurrent edits, for example from the console, follow last-writer-wins.

=== "Console"

    1. Open the deployment environment and go to **Variables**.
    2. Choose **Add environment variable**, enter the **Variable name** and its value.
    3. Save with **Save and Deploy** to redeploy the deployment environment now, or **Plan Deploy** to preview.

Deployed services only pick up changes at their next deploy. Add `--deploy` to `set` or `unset` to deploy immediately. Production environments need `--confirm-production`.

## Store a secret in Secret Manager

```bash title="Terminal"
alis environment set acme.sh.<env-id> STRIPE_KEY=sk_live_... --secret
```

The value is written as a new version of a Secret Manager secret named after the variable in the deployment environment's Google Cloud project, and is never stored or returned by Alis. Such a variable is left out of deployments; read it from your Terraform with `data "google_secret_manager_secret_version"`. Setting it again without `--secret` writes a new secret version; `--secret=false` with a value moves it back into Alis. The console marks these as **Stored in Secret Manager**.

## Write the variables to your machine

```bash title="Terminal"
alis environment refresh acme.sh.<env-id> --output ~/alis.build/acme/build/sh/.alis/.env
```

The file is written with owner-only permissions and only the path and variable names are printed. `alis run` loads this file. Add `--key-path <file>` to write a service account key and set `GOOGLE_APPLICATION_CREDENTIALS` in the file. `--reveal` prints the file to stdout instead and asks for approval.

## Related

- [Write infrastructure with Terraform](https://docs.alisx.com/how-to/alis-build/write-infrastructure-with-terraform.md)
- [Run a service locally](https://docs.alisx.com/how-to/alis-build/run-a-service-locally.md)
- [Terraform variables](https://docs.alisx.com/reference/dbd/terraform-variables.md)