envstack
Environment variable composition and activation layer for tools and processes.
envstack is what
.envfiles 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 environments are layered hierarchically, with later layers inheriting from and overriding earlier ones.
flowchart LR
default[default.env] --> prod[prod.env]
prod --> dev[dev.env]
prod --> test[test.env]
Later layers override earlier ones. 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.
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}
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
Secrets and encryption
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.
Documentation
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
File details
Details for the file envstack-1.0.1.tar.gz.
File metadata
- Download URL: envstack-1.0.1.tar.gz
- Upload date:
- Size: 62.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/5.1.1 CPython/3.8.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
84a69359112d88f95bc2dfd768daf611706ea603acc40e1a8c1c2dd16deaca33
|
|
| MD5 |
9ce1ff0b8ba609dcbe7f93309bea6c97
|
|
| BLAKE2b-256 |
e5d8d9355381e73ac2530790a7547dca2c2767f626f47888819923e1c12ebc1f
|
