envstack

Environment variable composition and activation layer for tools and processes.

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

Why envstack?

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

envstack focuses on configuration and activation, not dependency resolution.

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

Installation

The easiest way to install:

pip install -U envstack

Quickstart

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 the unresolved environment (before variable expansion):

$ envstack -u
DEPLOY_ROOT=${ROOT}/${ENV}
ENV=prod
ENVPATH=${DEPLOY_ROOT}/env:${ENVPATH}
HELLO=${HELLO:=world}
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

How envstack finds environments

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

In this case, environments in dev override or layer on top of environments in prod.

Converting .env files

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

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

Running Commands

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

Documentation

• Design & philosophy → docs/design.md
• Examples & patterns → docs/examples.md
• Tool comparisons → docs/comparison.md
• FAQ & gotchas → docs/faq.md
• API docs → docs/api.md