mutagent env

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 <name>. Commands never print stored values, only names and fingerprints. Model keys do not go in an Environment; they come from LLM providers.

Before you start

Sign in and select a workspace: see Installation. Environments belong to the selected workspace, or the one --workspace <name-or-id> 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.

mutagent env set ci DATABASE_URL=<database-url> --secrets-from-file .env.secrets --json

Here .env.secrets holds KEY=VALUE lines, such as GITHUB_TOKEN=<github-token>. With --json, success returns:

{
  "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 <KEY=VALUE...>`	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 <path>`	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 <path>`	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.

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.

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.

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.

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 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.

mutagent env unset demo GREETING --force

If it fails

Exit code	Cause	Fix
3	Not signed in, or no workspace selected.	See 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` 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

Account

Workspace

Helix

Setup

Before you start

mutagent env set

mutagent env list

mutagent env show

mutagent env unset

mutagent env delete

unset and delete need —force

If it fails

​Before you start

​mutagent env set

​mutagent env list

​mutagent env show

​mutagent env unset

​mutagent env delete

​unset and delete need —force

​If it fails

Before you start

mutagent env set

mutagent env list

mutagent env show

mutagent env unset

mutagent env delete

unset and delete need —force

If it fails