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

# vers env

> Manage environment variables that are injected into newly-created VMs.

`vers env` manages environment variables that Vers injects into new VMs at boot. The variables are written to `/etc/environment`, so they're available to SSH sessions and anything launched via `vers execute`.

<Note>
  `vers env` only affects **newly-created** VMs. Existing VMs keep the environment they were booted with.
</Note>

## Synopsis

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers env list                              # Show all configured variables
vers env list --format json                # Machine-readable
vers env set KEY VALUE                     # Set (or update) a variable
vers env delete KEY                        # Remove a variable
```

## Subcommands

### `vers env list`

List all environment variables configured for your account.

| Option          | Description             |
| --------------- | ----------------------- |
| `--format json` | Machine-readable output |

Aliases: `ls`.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers env list
vers env list --format json | jq '.[].key'
```

### `vers env set`

Set an environment variable.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers env set KEY VALUE
```

<Info>
  **Constraints**

  * `KEY` must be a valid shell identifier: letters, digits, underscores; cannot start with a digit.
  * `KEY` is at most 256 characters.
  * `VALUE` is at most 8192 characters.
</Info>

Examples:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers env set DATABASE_URL postgres://localhost/mydb
vers env set API_KEY secret123
vers env set DEBUG true
```

### `vers env delete`

Remove an environment variable. The key is no longer injected into new VMs; existing VMs are unaffected.

Aliases: `del`, `rm`, `remove`.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers env delete DATABASE_URL
vers env delete API_KEY
```

## How it works

<Steps>
  <Step title="Stored per account">
    Variables live on your Vers account, not on any single VM.
  </Step>

  <Step title="Injected at VM boot">
    When a new VM is provisioned (`vers run`, `vers branch`, `vers run-commit`, `vers build`), the orchestrator writes every variable to `/etc/environment` before handing the VM over.
  </Step>

  <Step title="Available to sessions and exec">
    Login shells, SSH sessions (`vers connect`), and commands run via `vers execute` all see the variables.
  </Step>
</Steps>

## Use cases

* **Secrets**: API keys, database URLs, webhook tokens — available to every VM without leaking into your Dockerfile or `vers.toml`.
* **Feature flags**: `DEBUG=true`, `FEATURE_X=on`.
* **Per-account defaults**: any variable you want every VM you create to inherit.

For secrets you want scoped to a single commit rather than your whole account, bake them into a commit with `vers build` + `ENV` or write to `/etc/environment` in a `RUN` step.

## Common Patterns

### Bulk-load from a local .env file

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
while IFS='=' read -r key value; do
  [ -n "$key" ] && [ "${key#\#}" = "$key" ] && vers env set "$key" "$value"
done < .env
```

### Clear every variable

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
vers env list --format json | jq -r '.[].key' | xargs -n1 vers env delete
```

### Verify injection on a fresh VM

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
VM=$(vers run --wait --format json | jq -r .root_vm_id)
vers execute "$VM" -- cat /etc/environment
```

## See also

* [vers build](/cli-reference/build) — bake environment into a specific commit via `ENV`
* [vers execute](/cli-reference/execute) — commands inherit `/etc/environment`
* [vers connect](/cli-reference/connect) — SSH sessions inherit `/etc/environment`