Valet|Docs
Sign up

CLI: Environment Variables

The valet env command family manages environment variables scoped to orgs or agents. Env vars come in two kinds. Secret vars (the default) hold credentials used by integrations and channels at runtime — the agent can invoke tools that depend on them but never sees the values. Plain vars are delivered to the agent's environment as ordinary unix environment variables, readable from bash ($NAME) and from code the agent writes, and their values are displayed in list output.

Reference an env var of either kind in integration or channel configuration using {{NAME}} syntax. At deploy time, Valet resolves these references and injects the actual values.

# Reference an env var in an integration
valet connectors create my-api \
  --transport stdio \
  --command npx \
  --args -y,@example/server \
  --env API_KEY={{MY_API_KEY}}

List env vars

valet env [--org <org>] [--agent <agent>]

Running valet env with no subcommand lists the effective environment for the given scope. Plain values are shown inline; secret values are masked.

Listing with --agent shows the effective environment the runtime sees: the agent's own vars plus the org vars it inherits, each tagged with its kind and scope. When an agent-scoped var has the same name as an org var, the agent value wins and the row is marked overrides org.

$ valet env --agent abb-luma-bot
Environment for abb-luma-bot agent in valetdotdev org:
GITHUB_TOKEN    secret  •••        agent (overrides org)
REGION          plain   us-east-1  org (inherited)
STRIPE_API_KEY  secret  •••        org (inherited)

Set env vars

valet env set <NAME=VALUE>... [--plain] [--org <org>] [--agent <agent>] [--no-wait]

Creates or updates one or more env vars in a single atomic operation — either all are persisted or none are. The kind defaults to secret; pass --plain for values the agent should read directly from its environment. All vars in one invocation share a kind, and the command echoes the kind it applied. A name is unique within its scope across both kinds; to change a var's kind, unset it and set it again.

You must specify exactly one scope: --org or --agent (or run from a linked agent directory).

  • Org-scoped env vars are shared across agents in the org. Setting one redeploys the agents that use it.
  • Agent-scoped env vars trigger an automatic redeploy of the agent and override org-scoped env vars of the same name.
  • --no-wait skips waiting for the redeploy to complete.
$ valet env set GITHUB_TOKEN=ghp_abc123
Setting GITHUB_TOKEN on my-agent agent in acme org... done
Set GITHUB_TOKEN (secret)
Waiting for agent to start... done

$ valet env set REGION=us-east-1 --plain --agent my-agent
Setting REGION on my-agent agent... done
Set REGION (plain)
Waiting for agent to start... done

$ valet env set A=1 B=2 C=3 --plain --org my-org
Setting A, B, C in my-org org... done
Set 3 env vars (plain)

Plain var names that would collide with the runtime's own environment — the VALET_ and LD_ prefixes and names like PATH and HOME — are reserved and rejected.

Unset env vars

valet env unset <NAME> [--org <org>] [--agent <agent>] [--force] [--no-wait]

Removes an env var of either kind and reports the kind that was removed. If the var is referenced by an integration or channel via {{NAME}}, the command fails unless --force is passed. Unsetting triggers a redeploy; use --no-wait to skip waiting for the agent to become ready.

$ valet env unset REGION
Unsetting REGION on my-agent agent in acme org... done
Unset REGION (plain)
Waiting for agent to start... done

$ valet env unset API_KEY --org my-org
Unsetting API_KEY in my-org org... done
Unset API_KEY (secret)

Channel secrets

Webhook channels use managed signing secrets to verify inbound requests. These secrets are created automatically when you add a catalog channel or create a webhook channel with valet channels create webhook. The managed field in the channel output is the secret name stored in valet env.

To rotate a managed signing secret, use valet env set MANAGED_SECRET_NAME=newvalue --org <org>. Use --secret-name on valet channels create webhook to reference an existing secret instead of auto-generating one (for services like Stripe or Svix where you control the signing key).

Examples

# Set an org-scoped secret
valet env set GITHUB_TOKEN=ghp_abc123 --org acme

# Set an agent-scoped plain var
valet env set REGION=us-east-1 --plain --agent my-agent

# List the effective environment for an agent
valet env --agent my-agent

# Unset an org env var
valet env unset GITHUB_TOKEN --org acme