Running Projects
How to execute commands with environment variables and secrets loaded from your project configuration.
There are 2 ways to use better-env to run projects:
1) Start an interactive shell
You can start an interactive shell with secrets loaded by running the following command:
bnv shell
# python3 main.py
exitThis will start an interactive shell with the secrets loaded from your project configuration.
You can run any commands/programs here and they will have access to the secrets.
Type exit to exit the shell.
2) Run the command directly
You can run a command directly by running the following command:
bnv run YOUR COMMANDFor example:
bnv run python3 main.pyThis will run the command with the environment variables and secrets loaded from your project configuration. This is how it works:
- It reads the
.better-envfile in your current directory to determine which secrets to load. - Then it uses your OpenPGP key to decrypt them and fetch them from the global store.
- It internally runs the command with the environment variables and secrets loaded like so:
python3 main.py KEY1=VALUE1 KEY2=VALUE2 ...This method is way safer and the recommended way to use better-env since only the child process will have access to the secrets.
bnv shell vs bnv run
bnv shell | bnv run | |
|---|---|---|
| How it works | Starts an interactive subshell with secrets injected into its environment; variables exist only inside that subshell. | Starts the command in a child process with secrets injected only for that process; parent shell remains untouched. |
| Pros | Great for interactive sessions; can run multiple commands without prefixing; isolated from the parent shell; secrets cleaned up when you exit. | Safer by default; secrets are ephemeral to the child process; no shell setup required; ideal for scripts/CI and one-off commands; automatic cleanup. |
| Cons | Secrets live for the lifetime of the subshell and can be inherited by any processes you launch from it; requires staying in that shell. | Must prefix each command; slightly less convenient for long interactive sessions. |
Prefer bnv shell for most workflows; use bnv run when you need to run a one-off command with secrets.