Pular para o conteúdo principal
informação
Esta página ainda não foi traduzida. Você está lendo a versão em English.

envshed run

Run a command with secrets injected as environment variables.

observação

Secret values may contain secret references (e.g. ${DB_HOST} or ${prod.API_URL}). These are resolved server-side before the CLI receives them, so injected variables hold fully expanded values. References you don't have read access to are left literal.

Usage​

terminal
envshed run [-o <org>] [-p <project>] [-e <env>] -- <command...>

Options​

FlagDescriptionDefault
-o, --org <slug>Organization slugFrom config
-p, --project <slug>Project slugFrom config
-e, --env <slug>Environment slugFrom config
--redactMask secret values in the command's stdout and stderrOn in agent mode and with --oidc
--no-redactDo not mask output, even in agent mode
--oidc <policy>Sign in with the job's GitHub Actions ID token, using this trust policy. Cannot be used with --watch or ENVSHED_TOKEN.ENVSHED_OIDC_POLICY

Arguments​

ArgumentDescription
command...The command to run (everything after --)

:::tip Always put -- before the command Without --, run still reads its own options anywhere in the line, even after the command. envshed run node app.js -e prod runs node app.js against prod, and envshed run node app.js --no-redact turns masking off. After --, every argument goes to the command unchanged: envshed run -- node app.js -e prod passes -e prod to node. :::

How it works​

  1. Fetches secrets from the API
  2. Merges them into the current environment variables (secrets override existing vars)
  3. Spawns the command as a child process
  4. Exits with the same exit code as the child process

No .env file is written to disk - secrets exist only in the process environment.

How the command starts​

Several arguments are passed to the program exactly as your shell left them, the way env, sudo and docker exec do. Quotes, spaces, $, parentheses and globs inside an argument reach the program unchanged:

terminal
envshed run -- node -e "console.log('ready')"
envshed run -- awk '{print $1}' access.log
envshed run -- FOO=1 node server.js # FOO is set for the program, like in a shell

A single argument is a shell line, run by /bin/sh (cmd.exe on Windows). Use it when the command needs the shell, for example to read an injected variable, chain commands or redirect output:

terminal
envshed run -- 'npm test && npm run build'
envshed run -- 'psql "$DATABASE_URL" -c "select 1"'
envshed run -- sh -c 'psql "$DATABASE_URL"' # same thing, spelled out

A command made of several arguments starts directly, with no shell in between. Signals such as SIGTERM from docker stop or a deploy then reach your program, so its graceful shutdown runs. This holds on every Linux image, including Debian and Ubuntu, whose /bin/sh would otherwise sit between run and the program, and in images that have no shell at all. To make sure signals reach a program started from a shell line, put exec in front of it, for example envshed run -- "exec node server.js > app.log".

On Windows, npm and other .cmd files are found and started the same way, with each argument quoted for cmd.exe.

If the program cannot be found, run prints an error and exits with 127, as a shell would.

:::note Changed in 0.20.0 Before, run joined several arguments into one shell line, so envshed run -- node -e 'console.log(1)' failed, and envshed run -- echo '$API_KEY' expanded the variable. Now that argument stays literal. Write envshed run -- 'echo $API_KEY' or envshed run -- sh -c 'echo $API_KEY' to have the shell expand it. :::

Disabled secrets​

Disabled secrets are not injected into the child process - their values are omitted from consumption. When the environment contains disabled secrets, the CLI prints a dim informational line after loading:

2 disabled secrets skipped

Re-enable a secret with envshed secret enable <KEY> (or from the dashboard) to inject it again.

Examples​

terminal
# Run a Node.js app with secrets
envshed run -- npm start

# Run a one-off script
envshed run -- node scripts/migrate.js

# Run with a specific environment
envshed run -e production -- npm run seed

# Run any command
envshed run -- docker compose up

# Monorepo: run from a workspace directory
cd apps/api && envshed run -- npm start

# Monorepo: run with explicit workspace from root
envshed --workspace apps/api run -- npm start

Monorepo behavior​

In a monorepo with workspaces configured:

  • Inside a workspace directory: injects that workspace's secrets, runs the command in that directory
  • At the monorepo root with --workspace: injects the specified workspace's secrets, runs in that workspace's directory
  • At the monorepo root without --workspace: errors - you must specify which workspace to use

Watch Mode​

Add --watch to auto-restart the command whenever remote secrets change.

terminal
envshed run --watch -- npm start
envshed run --watch --interval 60 -- node server.js

How watch mode works​

  1. Fetches secrets and spawns the command as normal, remembering the environment version that came with them, so a change made while the command starts is not missed
  2. Polls GET /api/v1/version at the configured interval using ETag/304 (no unnecessary work when secrets are unchanged)
  3. When a change is detected, fetches the new secrets first. If that fails, the running process keeps going and the next poll tries again
  4. Then sends SIGTERM to the running process and waits for it to exit (SIGKILL after 10 seconds) before starting it again with the new secrets
  5. Press Ctrl+C to stop watching - the CLI kills the child process cleanly before exiting

--interval only works with --watch; -w is the global --workspace option, not --watch.

Watch mode options​

FlagDescriptionDefault
--watchEnable watch modeoff
--interval <seconds>Poll interval (minimum: 10s)30

Security​

The CLI's own ENVSHED_TOKEN and ENVSHED_API_URL variables are stripped from the child process environment before spawning. Only the fetched secrets and the original inherited environment (minus those two variables) are passed to the command.

With output masking on, each restarted process is masked with the values it was started with, and stopping the watcher waits up to 2 seconds for the process's shutdown output.

Rate limiting​

On a 429 response, the poll interval doubles (up to 5 minutes) without restarting the child process. Normal cadence resumes on the next successful poll.

Agent sessions​

If you started an agent session for this organization, project and environment, run uses its token instead of your login and says so. When that session has expired, run stops with an error rather than using your login. ENVSHED_TOKEN still takes precedence over a session.

GitHub Actions​

envshed run --oidc <policy> needs no stored credential. See GitHub Actions with OIDC. The session stays in memory, and the command does not receive it or the variables needed to ask GitHub for another ID token.

Output masking​

When a coding agent runs a command, whatever the command prints ends up in the agent's context and transcript. Output masking replaces known secret values with [ENVSHED:KEY_NAME] in stdout and stderr, so envshed run -- printenv shows this instead of the values:

DATABASE_URL=[ENVSHED:DATABASE_URL]
PORT=3000
cuidado

Masking reduces accidental leaks. It is not a barrier against an agent with shell access: a transformed value or a file written by the command gets around it. The agent hooks block --no-redact and changes to ENVSHED_AGENT_MODE in front of envshed run, but only for the commands they can read. Limits that must hold, such as which secrets a token can read, belong on the server.

When it is on​

Masking is on by default only in agent mode and with --oidc. The first match decides:

PrioritySourceEffect
1--redact or --no-redactOn or off
2--oidc or ENVSHED_OIDC_POLICYOn, since a job moving from secrets.X would otherwise lose GitHub's log masking
3ENVSHED_AGENT_MODE0, false, no or off turn it off; any other non-empty value turns it on
4CLAUDE_CODE_CHILD_SESSION=1On. Claude Code sets this in the commands it launches

Having no TTY does not turn masking on, because scripts and CI consume this output. Outside agent mode, the command runs exactly as it always has: same stdio: "inherit", same output.

CLAUDECODE is not used, because IDE extensions also set it in the integrated terminal, where a person may be typing. Set ENVSHED_AGENT_MODE=1 yourself for other agents, for an MCP server launched by Claude Code (those do not receive CLAUDE_CODE_CHILD_SESSION), and for Claude Code versions that do not set the variable yet.

What gets masked​

Each value is matched as is, URL-encoded, and as base64 of the whole value (standard, without padding, URL-safe, and with a trailing newline, as in printenv KEY | base64). The longest match wins, so a value containing another key's value is masked whole.

A value is also matched in the escaped forms that ordinary logging and shells print:

  • JSON, as in JSON.stringify or Python's json.dumps, including JSON inside JSON.
  • String literals, as in util.inspect, repr or bash's $'...'.
  • Shell quoting, as in export -p, single quotes and printf %q.

Each line of a multi-line value is matched on its own too, raw and escaped, because sed -n 2p or an unquoted echo $KEY prints the lines apart. A PEM key's BEGIN and END lines are left out, since they are the same in every key.

To keep ordinary output readable, a value is not masked when any of these is true:

  • It is shorter than 8 bytes, such as true or 3000.
  • It is a common configuration word, such as development, production or localhost.
  • It is a bare URL scheme, such as https:// or s3://, or an AWS region, such as us-east-1.
  • It is made only of digits and is shorter than 12 characters, such as a timeout.
  • It is repetitive, with Shannon entropy below 2.5 bits per byte, such as aaaaaaaa.

The same rule applies to each line of a multi-line value, so a short last line of a PEM key can still print when it appears alone.

The CLI prints on stderr how many values are masked and how many were skipped.

Not covered: values split across the output by other text or color codes, base64 wrapped across lines, partial values, other encodings and escapings, and anything the command writes to a file or sends over the network. When two different values overlap without one containing the other, the end of the second one is left unmasked.

What changes for the command​

Masking has to sit between the command and the output, so stdout and stderr become pipes:

  • No colors or terminal UI. The command sees no TTY on stdout and stderr, so many tools drop colors, progress bars and cursor control. Stdin stays connected as usual.
  • Slight hold-back. Output is emitted immediately, except for trailing bytes that could be the start of a value. Those wait up to 50 ms for the rest, so prompts are not noticeably delayed. From 8 bytes on they wait up to 2 seconds, because that much of a value is rarely a coincidence.
  • A flush can emit part of a value. If a command writes the first part of a value and pauses longer than that wait before writing the rest, the first part has already been printed and the rest is not recognized. A first part under 8 bytes is only held for 50 ms.
  • Background processes. After the command exits, the CLI waits for its output to finish, for up to 2 seconds if something it left running holds the pipes open. After that, that process's output is no longer shown. A slow consumer of the output extends this wait.

Signal forwarding and the exit status work the same in both modes, including death by signal.

Effective context​

Environment selection uses -e > ENVSHED_ENV > personal checkout/workspace selection > shared default. CI ignores personal selections. Inspect the target with envshed branch; see configuration resolution. Selecting an environment does not export values.

Each run loads current values from the API. It does not require a prior pull or a local file refresh.