Environment variable composition and activation layer for tools and processes.

envstack is what .env files wish they were when they grew up.

• Hierarchical environment composition
• Explicit precedence and overrides
• Late-bound environment activation
• Shared, policy-driven environments
• Inspectable and deterministic behavior

envstack environments are layered explicitly. Stack files identify what is being configured, directories identify scope, and ordering determines precedence.

flowchart LR
  default[default.env] --> prod[prod.env]
  prod --> dev[dev.env]
  prod --> test[test.env]

Later layers override earlier ones within the resolved stack. Across directories, ENVPATH ordering defines precedence: earlier paths win when the same stack exists in multiple locations. Use envstack -t VAR to trace where a value comes from. envstack focuses on configuration and activation, not dependency resolution.

For the core concepts, see docs/index.md.

The easiest way to install:

pip install -U envstack

Start by getting the latest default.env example file:

curl -o \
default.env \
https://raw.githubusercontent.com/rsgalloway/envstack/master/examples/default/default.env

Running envstack will launch a new shell session with the resolved environment:

$ envstack
🚀 Launching envstack shell... (CTRL+D or "exit" to quit)
(prod) ~$ echo $ENV
prod

To inspect selected raw values, use envstack default -u PATH PYTHONPATH. Put stack names before -u, as with -r; omit variable names to show all values.

To inspect the unresolved environment (before variable expansion):

$ envstack -u
DEPLOY_ROOT=${ROOT}/${ENV}
ENV=prod
ENVPATH=${DEPLOY_ROOT}/env:${ENVPATH}
LOG_LEVEL=${LOG_LEVEL:=INFO}
PATH=${DEPLOY_ROOT}/bin:${PATH}
PS1=\[\e[32m\](${ENV})\[\e[0m\] \w\$ 
PYTHONPATH=${DEPLOY_ROOT}/lib/python:${PYTHONPATH}
ROOT=/mnt/pipe
STACK=default

$ envstack -r DEPLOY_ROOT
DEPLOY_ROOT=/mnt/pipe/prod

envstack discovers environment definitions via the ENVPATH environment variable. ENVPATH is to envstack what PATH is to executables:

ENVPATH=/path/to/dev/env:/path/to/prod/env

ENVPATH ordering defines precedence. Earlier paths win when the same stack exists in multiple locations, so a stack found in /path/to/dev/env overrides the same stack found in /path/to/prod/env.

As a rule of thumb:

Files identify stacks; directories identify scope; ENVPATH defines precedence.

Convert existing .env files to envstack by piping them into envstack:

cat .env | envstack --set -o out.env

To run any command line executable inside of an environment stack, where [COMMAND] is the command to run:

$ envstack [STACK] -- [COMMAND]

For example:

$ envstack -- echo {ENV}
prod

Example of injecting environment into a subprocess:

$ echo "console.log('Hello ' + process.env.ENV)" > index.js
$ node index.js 
Hello undefined
$ envstack -- node index.js 
Hello prod

envstack supports optional encryption of environment values when writing environment files, allowing sensitive configuration to be safely stored, committed, or distributed.

Encryption protects values at rest and integrates with environment stacks and includes. envstack does not attempt to be a full secret management system.

See docs/secrets.md for details.

• Design & philosophy
• Examples
• Wrappers
• Tool comparisons
• Secrets and encryption
• FAQ & gotchas
• API docs