Environment store

Store and manage environment variables persistently, in a hierarchy, on different backends: a local file, PostgreSQL, AWS Parameter Store or AWS Secrets Manager. Use it from Python, the command line or an interactive terminal UI.

• Hierarchical: organisation > project > environment > service. Child levels override their parents.
• Pluggable backends: the same API, CLI and TUI for every store, and a transfer command to move between them.
• Three interfaces: EnvironmentStoreManager in Python, the environment-store CLI, and a Textual-based TUI.
• Agent friendly: ships a skill that teaches LLM agents to use the CLI safely.

root                      LOG_LEVEL=info
└── acme                  (organisation)       DB_HOST=db.acme.internal
    └── webapp            (project)
        └── prod          (environment)        LOG_LEVEL=warning
            └── api       (service)            PORT=8080

The resolved variables of acme / webapp / prod / api are all of the above combined, deeper values winning: DB_HOST=db.acme.internal, LOG_LEVEL=warning, PORT=8080.

Quickstart

uv add "environment-store[tui]"        # or: pip install "environment-store[tui]"

export ENVIRONMENT_STORE_BACKEND=json ENVIRONMENT_STORE_JSON_FILE=./store.json

environment-store set LOG_LEVEL info
environment-store set PORT 8080 -o acme -p webapp -e prod -s api
environment-store list -o acme -p webapp -e prod -s api --resolved
environment-store tui

from environment_store import EnvironmentStoreManager
from environment_store.adapters.json import JsonFileAdapter

manager = EnvironmentStoreManager(adapter=JsonFileAdapter("./store.json"))
manager.set_variable("DB_HOST", "localhost", organisation="acme", project="webapp")
manager.get_resolved_variables(organisation="acme", project="webapp")

The full walkthrough is in the Quickstart.

Documentation

Installation

The core package depends only on pydantic and includes the JSON backend and the CLI. Everything else is an extra:

uv add "environment-store[full]"

More, including installing from git and running without installing, in the installation guide.

Python

Everything goes through EnvironmentStoreManager; only the adapter changes per backend. Pass the hierarchy as keyword arguments (organisation=, project=, environment=, service=); levels cannot be skipped.

manager.set_variables({"LOG_LEVEL": "INFO"}, organisation="acme")
manager.get_variable("DB_HOST", organisation="acme", project="webapp")  # exact level
manager.get_resolved_variables(organisation="acme", project="webapp")  # with parent levels
manager.get_child_levels(organisation="acme")  # ["webapp"]
manager.delete_level(organisation="acme", project="webapp", confirm="webapp")

Reading, writing, resolving, discovering, deleting and copying are covered in the Python guide.

Command line

environment-store set DB_HOST localhost -o acme -p webapp
environment-store get DB_HOST -o acme -p webapp
environment-store list -o acme --resolved --format json
environment-store import .env -o acme -p webapp -e dev
environment-store delete-level -o acme -p webapp --dry-run
environment-store transfer --dest-backend postgres --dest-database-url "$URL" --dry-run
environment-store migrate            # PostgreSQL schema

Commands: get, set, list, delete, import, children, delete-level, transfer, migrate, tui. Choose the backend with --backend or ENVIRONMENT_STORE_BACKEND. Data goes to stdout, messages to stderr, and exit codes are stable. See the CLI guide for every option.

Terminal UI

environment-store tui

A tree of your levels next to a table of their variables. Navigate with the arrow keys or hjkl; a add, e edit, d delete, n new level, x delete a level (you must type its name), r resolved view, v show values, q quit. See the TUI guide.

Storage backends

Options, IAM permissions, layouts and trade-offs are in Storage backends.

Development

uv sync && pre-commit install
uv run pytest && uv run ruff check && uv run ty check

The CLI, the TUI and any future frontend are thin layers over EnvironmentStoreManager; all logic lives in environment_store/core/. Architecture, testing, adding features and adapters, and database migrations are in the development guide. To add a new storage backend follow Adding a storage adapter.

License

MIT, see LICENSE.