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

# lua env

> Set, list, and delete the environment variables your code reads in the sandbox (.env) and in production (server-side)

`lua env` sets, lists, and deletes the variables your code reads through [`env`](/reference/sdk/env). `lua env sandbox` writes the project's `.env` file only; production variables are stored on the server. `lua test` reads `.env`; `lua chat -e sandbox` uploads the `.env` values with each sandbox version, and sandbox turns read them from the platform. The live agent reads the production variables, and changing them needs no push or deploy.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua env <environment> --list
lua env <environment> -k <KEY> -v <value>
lua env <environment> -k <KEY> --delete
lua env [<environment>]
```

## Description

The environment argument is `sandbox` (alias `sb`) or `production` (aliases `prod`, `prd`, `live`). `staging` and its aliases `stage` and `stg` are accepted and mean sandbox. An unknown value exits 2 with a suggestion. Using `--list`, `-k`, `-v`, or `--delete` without an environment also exits 2. With no argument and no flags the command asks which environment to manage and opens a menu to add, update, delete, or view a variable.

For the sandbox the command reads `./.env` and, on set or delete, rewrites the whole file as `KEY=value` lines; comments, blank lines, and quotes are dropped. Keep `.env` out of version control. For production, `--list` fetches the stored variables, a set sends the complete variable map with the change applied, and `--delete` removes one key. Both environments require a project and a credential.

A key must start with a letter or underscore and contain only letters, digits, and underscores; otherwise the command exits 2 with `Variable name must start with a letter or underscore and contain only letters, numbers, and underscores`. A set prints `Created <KEY>` or `Updated <KEY>` and never echoes the value. `--list` masks values to their first four characters followed by asterisks, and values of four characters or fewer entirely; the interactive menu's view action is the only way to print a full value. There is no `--json` output. Deleting a key that does not exist exits 1 with `Variable "<KEY>" not found`.

## Arguments

| Argument        | Values                             | Description                                                                                                             |
| --------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `<environment>` | `sandbox`, `production`, `staging` | Which variable set to manage. `staging` is an alias of `sandbox`. Aliases: `sb`, `stage`, `stg`, `prod`, `prd`, `live`. |

## Options

| Option                | Description                               | Default |
| --------------------- | ----------------------------------------- | ------- |
| `-k, --key <KEY>`     | Variable name to set or delete.           | —       |
| `-v, --value <value>` | Value to store; with `-k`.                | —       |
| `-d, --delete`        | Delete the `-k` variable.                 | off     |
| `--list`              | Print every variable with a masked value. | off     |

## Examples

Store an API key for local runs, then for the live agent:

```bash theme={null}
lua env sandbox -k WEATHER_API_KEY -v "wk_live_abc123"
lua env production -k WEATHER_API_KEY -v "wk_live_abc123"
```

List what production has; values are masked:

```bash theme={null}
lua env production --list
```

```text Output theme={null}

🌙 Environment Variables (Production)

ℹ️  No environment variables configured.

```

Delete a variable from production in a script:

```bash theme={null}
lua env production -k OLD_KEY --delete --ci
```

Flags without an environment are refused:

```bash theme={null}
lua env --list
```

```text Output theme={null}
✖ usage: Environment must be specified when using non-interactive options.
💡 Usage:
     lua env sandbox --list                    List sandbox variables
     lua env production -k KEY -v VALUE        Set variable
     lua env production -k KEY --delete        Delete variable
```

So is `-k` on its own:

```bash theme={null}
lua env production -k MY_VAR
```

```text Output theme={null}
✖ usage: Invalid usage: -k requires either -v VALUE to set or --delete to remove
💡 Examples:
     lua env production -k MY_VAR -v "value"     # Set variable
     lua env production -k MY_VAR --delete       # Delete variable
```

## Exit codes

| Code | Meaning                                                                                                                          |
| ---- | -------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | Listed, set, or deleted.                                                                                                         |
| `1`  | `Variable "<KEY>" not found`, or the `.env` write or the server update failed.                                                   |
| `2`  | Unknown environment, flags without an environment, an incomplete flag combination, an invalid key name, or not inside a project. |
| `9`  | No credential, or the server rejected it.                                                                                        |
| `11` | The server or network is unavailable.                                                                                            |

## See also

* [About environments](/concepts/environments) — what sandbox and production share
* [`env`](/reference/sdk/env) — reading variables in code
* [Call your API](/build/call-your-api) — secrets in tools
* [Environment variables](/reference/cli/environment-variables) — the variables that configure the CLI itself
* [`lua production`](/reference/cli/production) — `lua production env` lists the same production variables