envstack 0.9.6

Environment variable composition layer for tools and processes.

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