pw-env

Appearance

Star

First project ​

The fastest way to adopt pw-env is to keep the shape of your .env file, then let the CLI fill in secrets at runtime.

1. Create the project env file ​

Use empty values for variables that should be loaded from the default backend:

dotenv
DATABASE_URL=
API_KEY=

Mix in explicit references when a key should always come from a specific backend:

dotenv
DATABASE_URL=op://Development/my-app/database_url
API_KEY=bw://env-secrets/my-app/api_key
LOG_LEVEL=debug

Plaintext values are left alone until you migrate them. Add # pw-env:ignore when a local value should never be treated as a migration candidate.

2. Create the global config ​

Start from the built-in template:

console
$ pw-env config-template > ~/.config/pw-env/config.toml

Pick a default backend for empty values.

toml
[defaults]
backend = "op"

[defaults.op]
vault = "Development"
toml
[defaults]
backend = "bw"

[defaults.bw]
folder = "env-secrets"
toml
[defaults]
backend = "gpg"

[defaults.gpg]
file_pattern = ".env.gpg"
recipient = "your-email@example.com"

3. Export the values into your shell ​

console
eval "$(pw-env export . --shell bash)"
console
pw-env export . --shell fish | source
powershell
Invoke-Expression (& pw-env export . --shell powershell)

The first time a project .env would trigger secret fetching, pw-env asks you to approve it. The default approval is tied to the current .env hash, so changing the file causes a new approval prompt.

4. Inspect what pw-env sees ​

console
pw-env load .
pw-env check

pw-env load shows how each entry was classified before printing masked export output with only a short value prefix, which makes it a good first debugging command. Add --reveal only when you intentionally need to inspect the full resolved values.

5. Install automatic loading when you are ready ​

console
eval "$(pw-env init bash)"
console
eval "$(pw-env init zsh)"
console
pw-env init fish | source
powershell
Invoke-Expression (& pw-env init powershell)

Add the same command to your shell startup file so the hook is installed in every new session. For PowerShell, add it to your $PROFILE file.

To enable tab completion for pw-env commands, generate the completion script once and source it from the same startup file:

console
eval "$(pw-env completions bash)"
console
eval "$(pw-env completions zsh)"
console
pw-env completions fish | source
powershell
Invoke-Expression (& pw-env completions powershell)

See Shell integration for the full hook behavior.

See the full flow ​

This screencast walks through the same setup end to end with a GPG-backed project: create the global config, migrate plaintext secrets, install the shell hook, and watch values load and clear automatically as you move between project directories.

Screencast showing pw-env configuration, migration, shell init, and automatic loading on directory changes

Next steps ​

Move to Shell integration when you want automatic loading on cd, or to Migrating plaintext secrets if your current .env file still contains credentials.