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 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.
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 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
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
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;
ENVPATHdefines precedence.
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
Metadata
Release files for envstack 1.0.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| envstack-1.0.5.tar.gz | 65.7 kB | Without provenance | Details for envstack-1.0.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| envstack-1.0.5-py3-none-any.whl | Python 3 | none | any | Details for envstack-1.0.5-py3-none-any.whl |
Total release size: 112.9 kB
Release files / envstack-1.0.5.tar.gz
| Download URL | envstack-1.0.5.tar.gz |
|---|---|
| Size | 65.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f438a39bf8915092ff5037d095b4458dbde4b8bd3bad62c0d5f94046cc571a64
|
|
BLAKE2b-256 checksum How to use checksums |
ae42a85c02d767238607a29c4193d4009a6673f76d341cd2784354843d06184c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.10
|
Release files / envstack-1.0.5-py3-none-any.whl
| Download URL | envstack-1.0.5-py3-none-any.whl |
|---|---|
| Size | 47.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5e0f1620b5364594a81f87e444502ed3fbd2cc4abd8655b89ae6792184d0cb01
|
|
BLAKE2b-256 checksum How to use checksums |
09bcec7a9ba99caafbf0b7ecd743d94da76ab7ab2780e39b773cbab573cf3a43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.10
|
Security for envstack 1.0.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.