> ## Documentation Index > Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt > Use this file to discover all available pages before exploring further. # mutagent env > Create and manage workspace Environments: the variables and secrets your cloud sessions' tools need. An Environment holds the variables and secrets your cloud sessions' tools need, such as a GitHub token or a database URL. Load one into a run with `--env `. Commands never print stored values, only names and fingerprints. Model keys do not go in an Environment; they come from [LLM providers](/cli/commands/providers). ## Before you start Sign in and select a workspace: see [Installation](/cli/installation). Environments belong to the selected workspace, or the one `--workspace ` names. Without a workspace, every command on this page exits 3. ## mutagent env set Create an Environment, or add entries to an existing one. Entries you do not name are kept. Both variables and secrets are set as environment variables in the sandbox. A name cannot be both. ```bash theme={null} mutagent env set ci DATABASE_URL= --secrets-from-file .env.secrets --json ``` Here `.env.secrets` holds `KEY=VALUE` lines, such as `GITHUB_TOKEN=`. With `--json`, success returns: ```json theme={null} { "success": true, "environment": { "name": "ci", "vars": [{ "name": "DATABASE_URL", "fingerprint": "…" }], "secrets": [{ "name": "GITHUB_TOKEN", "fingerprint": "…" }] }, "variables": ["DATABASE_URL"], "secrets": ["GITHUB_TOKEN"], "replaced": false, "created": true } ``` Check that each name is in `variables` or `secrets` as you meant. `created` is `true` when this command made the Environment. | Argument or flag | What it does | | - | - | | `KEY=VALUE` | Set a variable. | | `-s, --secret ` | Set a secret. Secrets are stored encrypted and never shown again. `--secret` takes every `KEY=VALUE` after it, so put variables first: `env set demo A=1 --secret TOKEN=x`. | | `--from-file ` | Read variables from a file of `KEY=VALUE` lines. A value on the command line is used instead of the same name in the file. | | `--secrets-from-file ` | Read secrets from a file of `KEY=VALUE` lines. | | `--replace` | Replace the whole Environment. Entries you do not name are deleted, secrets included. Needs `--force`. | | `-f, --force` | Required with `--replace`, in every mode. Without it, `--replace` refuses, names the entries it would remove, and writes nothing. A merge needs no `--force`. | | `--allow-provider-key` | Allow a variable named like an LLM provider key, such as `ANTHROPIC_API_KEY`. It replaces the workspace key for runs that load this Environment. Without it, such a name is refused. | Names: Environment names use letters, digits, `.`, `_` and `-`, up to 64 characters. Entry names use `A-Z`, `0-9` and `_`, and do not start with a digit. A value may contain `=`: `TOKEN=a=b` stores `a=b`. An Environment holds up to 64 KiB. To keep secrets out of your shell history, pass them with `--secrets-from-file`. ## mutagent env list List the workspace's Environments and their entry names. `mutagent env ls` is the same command. ```bash theme={null} mutagent env list --json ``` The JSON has `environments` (each with `name`, `vars`, `secrets`, `createdAt`, `updatedAt`) and `count`. `vars` and `secrets` list names and fingerprints, never values. An empty list means the workspace has no Environments yet. ## mutagent env show List one Environment's entry names, whether each is a variable or a secret, and a fingerprint of each value. An unknown name is an error. ```bash theme={null} mutagent env show ci ``` The fingerprint is 8 hex characters computed on the server with a key only the server holds. It stays the same while the value is unchanged, so comparing two `show` runs tells you whether a value changed. You cannot compute it yourself. To make sure a value is what you expect, set it again with `mutagent env set`. ## mutagent env unset Remove entries from an Environment. A name that does not exist is not an error. A removed secret cannot be read back, so the command needs `--force`. ```bash theme={null} mutagent env unset ci DATABASE_URL --force ``` | Flag | What it does | | - | - | | `-s, --secret` | The names are secrets. Without it, both variables and secrets are checked. | | `-f, --force` | Required. Without `--force` the command refuses and removes nothing. | ## mutagent env delete Delete an Environment and its secrets. `mutagent env rm` is the same command. Sandboxes that are already running keep the values they were given; the next run that names the Environment fails. ```bash theme={null} mutagent env delete ci --force ``` | Flag | What it does | | - | - | | `-f, --force` | Required. The command never asks for confirmation: without `--force` it refuses and deletes nothing. | See [Environments](/helix/cloud/environments) for size limits and which value is used when names collide. ## unset and delete need --force `mutagent env unset` removes values that cannot be read back, so it follows the rule for delete commands: it refuses without `--force` and sends nothing, with or without `--json`. The error code is `CONFIRMATION_REQUIRED` and the exit code is 1. The same applies to `env delete`. ```bash theme={null} mutagent env unset demo GREETING --force ``` ## If it fails | Exit code | Cause | Fix | | - | - | - | | 3 | Not signed in, or no workspace selected. | See [Installation](/cli/installation). | | 1 | An invalid entry name. The error names the key, never the value. | Use `A-Z`, `0-9` and `_`, not starting with a digit. | | 1 | A variable named like an LLM provider key, such as `ANTHROPIC_API_KEY`. | Add the key with [`mutagent providers add`](/cli/commands/providers#mutagent-providers-add) instead, or pass `--allow-provider-key`. | | 1 | `CONFIRMATION_REQUIRED`: `unset`, `delete` or `set --replace` without `--force`. | Confirm with the person, then add `--force`. | | 1 | `show` or `delete` with an unknown Environment name. | Check the name with `mutagent env list`. | See [Errors and exit codes](/cli/errors). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.