envshed run

Run a command with secrets injected as environment variables.

Usage

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

Options

Flag	Description	Default
-o, --org <slug>	Organization slug	From config
-p, --project <slug>	Project slug	From config
-e, --env <slug>	Environment slug	From config

Arguments

Argument	Description
command...	The command to run (everything after --)

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.

Examples

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

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
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, sends SIGTERM to the running process, waits for exit, then re-fetches secrets and re-spawns
4. Press Ctrl+C to stop watching — the CLI kills the child process cleanly before exiting

Watch mode options

Flag	Description	Default
--watch	Enable watch mode	off
--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.

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.