How do I use named env files?
Table of Contents
Compass reads .env at the repo root for database, NATS, and service
configuration. Named env files let you target a different host without
mutating the working .env.
1. Question
How do I use a named env file to target a remote host database or service fleet?
2. Answer
Pass --env <name> (shorthand resolving to .env.<name>) or
--env-file <path> before or after the sub-command. Compass reads
that file in place of the default .env.
# Target Newton's Postgres — no need to edit .env in place compass db status --env newton # reads .env.newton compass db recreate -y -k --env newton # Service and shell commands also support it compass services status --env newton compass services start --env newton compass shell --env newton # Full explicit path also works compass db status --env-file .env.newton # Flag position doesn't matter — before or after the sub-command compass --env newton db status compass --env-file .env.newton fleet
3. How it works
The flag is parsed early in compass.py main(), before command
dispatch, so it works with every sub-command. The resolved path is
passed to load_env() (in compass_db.py) and read by
_read_env_map() (in compass.py). Commands that don't need
environment config silently ignore it.
When no flag is given, the default .env at the repo root is used
— fully backwards compatible.
4. See also
- Compass component overview