div secrets

Synopsis

div secrets [--environment <env>] [--json]
div secrets set <name> [--from-env] [--environment <env>] [--products <products>]
div secrets products <name> <products> [--environment <env>]
div secrets rm <name> [--environment <env>]
div secrets env [ls]
div secrets env add <env>
div secrets env rm <env>

Manages the org’s secrets and the environments that hold them.

Environments and products

• An environment holds one value for each secret name. The same name can hold a different value in each environment.
• Every org has the default environment. It is listed first and cannot be deleted.
• Without --environment, set, products and rm act on default, and listing shows every environment.
• A secret’s products are runs, sandboxes or both, joined by commas. A new secret has runs,sandboxes unless you pass --products.

Product	Receives
Runs	Every secret in default whose products include runs. Secrets in other environments never reach a run.
Sandboxes	Only the secrets named with div sandbox create --secret, from the sandbox’s environment. Each must include sandboxes in its products.

See Keep each customer’s credentials in its own environment.

Subcommands

Subcommand	Description
(none), ls	List secrets with their environment, products and the date each was last set. Values are never shown.
set	Create a secret or replace its value. Reads the value from stdin, or from the environment with --from-env. Replacing a value keeps the secret’s products unless you pass --products.
products	Change which products receive a secret. The value is not changed.
rm	Delete a secret from one environment. Runs and sandboxes that have already started keep the value.
env, env ls	List environments with the number of secrets in each.
env add	Create an environment. It starts with no secrets.
env rm	Delete an environment and every secret in it, and print the secrets it deleted. Refused while any sandbox that is not deleted uses the environment.

Arguments

Argument	Description
<name>	Secret name: letters, digits and _, not starting with a digit. Names starting with DIVERGENT_ are reserved.
<products>	runs, sandboxes, or runs,sandboxes.
<env>	Environment name: lower case letters, digits and dashes, up to 63 characters, starting with a letter or digit.

Flags

Flag	Description	Default
--environment <env>	The environment to list, or to set, change or delete the secret in. The environment must exist; create it with div secrets env add.	list: every environment; others: default
--products <products>	set: the products that receive the secret.	new secret: runs,sandboxes; existing secret: unchanged
--from-env	set: read the value from the shell variable with the same name.	read stdin
--json	List as JSON.
--token <key>	API key to use.	see Configuration
--api-url <url>	API URL to use.	see Configuration

Values

• Maximum size: 64 KiB.
• One trailing newline is removed. Everything else is kept exactly.
• set rejects a value passed as an argument, and rejects stdin when it is a terminal, so the value never appears in shell history or on screen.

In a run

• The run’s log lists the names of the secrets it received.
• If a run prints a secret’s value, the log shows •••• instead. Values shorter than 6 bytes are not masked.
• A run’s --env value overrides a secret with the same name.

In a sandbox

• A sandbox receives only the secrets it names, from the environment it was created in. See Secrets.
• Resuming a sandbox reads the secrets again from the same environment. Resume is refused if a named secret was deleted or no longer includes sandboxes.
• A sandbox that names any secret cannot have a sandbox token, in any environment.

Permissions

Listing secrets and environments requires the secrets:read scope. Every other subcommand requires secrets:write. Keys created by div login have both. If your key is older and lacks them, run div login again.

Output

HF_TOKEN           default  runs,sandboxes  2026-09-22
WANDB_API_KEY      default  runs            2026-09-20
ANTHROPIC_API_KEY  acme     sandboxes       2026-10-01
3 secrets in 2 environments

The last line goes to stderr. The name is the first column, so div secrets | cut -d' ' -f1 lists names. With --json, each secret has name, environment, products, inserted_at and updated_at.

default  2 secrets
acme     1 secret   2026-10-01
2 environments

div secrets env lists environments, default first, with the number of secrets and the date each was created. default has no date. The last line goes to stderr. With --json, each has name, secrets and inserted_at, which is null for default.

set, products, rm, env add and env rm print one line on stderr. env rm names the secrets it deleted:

Deleted environment acme and its 2 secrets: GITHUB_TOKEN, NPM_TOKEN.

Exit codes

Code	Meaning
0	Success.
1	The API rejected the request.
2	Invalid arguments, --products on a subcommand other than set, a value passed as an argument, or a terminal on stdin.

Errors

Code	When
secret_not_found	No secret with that name in the environment. Run div secrets --environment <env> to list them.
unknown_environment	The environment does not exist. Create it with div secrets env add, or list environments with div secrets env ls.
environment_in_use	env rm while sandboxes that are not deleted use the environment. The message names them. Delete them with div sandbox rm first.
default_environment	env rm default. The default environment cannot be deleted. Delete its secrets one at a time with div secrets rm.
validation_failed	An invalid environment name, an invalid products value, or an environment that already exists.

Examples

printf %s "$HF_TOKEN" | div secrets set HF_TOKEN
div secrets set WANDB_API_KEY --from-env --products runs
div secrets set GCP_KEY < key.json
div secrets products GCP_KEY runs,sandboxes
div secrets env add acme
div secrets set ANTHROPIC_API_KEY --from-env --environment acme --products sandboxes
div secrets --environment acme
div secrets rm HF_TOKEN
div secrets env rm acme

See Pass credentials to a run and Keep each customer’s credentials in its own environment.