Configuration

Config Command

bwenv v2 has a built-in configuration system managed through an interactive TUI:

bwenv config

This opens a settings editor where you can toggle preferences with arrow keys.

Settings

Setting	Default	Description
Show Emoji	ON	Display emoji icons in bwenv output. Turn off for cleaner text-only output.
Show Direnv Output	OFF	Show or hide direnv’s own loading/unloading messages. When OFF, bwenv adds DIRENV_LOG_FORMAT="" to your shell RC file.
Show Export Summary	ON	Show the boxed summary of exported variables when secrets are loaded via direnv.
Auto Sync	ON	Automatically sync the vault before fetching secrets (Bitwarden only — runs bw sync).

Config File

Settings are persisted to:

~/.config/bwenv/config.json

Example contents:

{
  "show_emoji": true,
  "show_direnv_output": false,
  "show_export_summary": true,
  "auto_sync": true
}

You can edit this file manually if needed, but using bwenv config is recommended.

Project Files

.envrc

Generated by bwenv init in each project directory. Contains a single eval call that fetches secrets from your vault at load time:

# bwenv: provider=bitwarden folder="My Secrets"
# Run bwenv login to re-authenticate if session expires
eval "$(BW_SESSION='...' bwenv export --provider bitwarden --folder 'My Secrets')"

• No secrets are stored on disk (only session tokens, which expire)
• Secrets are fetched live from your vault each time direnv loads
• Add .envrc to your .gitignore

Config directory

~/.config/bwenv/
└── config.json    # User preferences

Environment Variables

Managed by bwenv

Variable	Description
BW_SESSION	Bitwarden session token. Set in .envrc by bwenv init/bwenv login. Expires after vault timeout.
DIRENV_LOG_FORMAT	Set to "" in your shell RC when “Show Direnv Output” is OFF, to suppress direnv messages.

Used by bwenv (CI/CD)

Variable	Description
BW_SESSION	Pre-set a Bitwarden session for non-interactive export
OP_SERVICE_ACCOUNT_TOKEN	1Password service account token for non-interactive export
BW_CLIENTID / BW_CLIENTSECRET	Bitwarden API credentials for CI authentication

Provider Integration

Bitwarden

• CLI: bw — Install
• Auth: Master password (prompted in TUI) or pre-set BW_SESSION
• Secrets: Custom fields on items within folders. Field name = env var name, field value = env var value.
• Sync: bw sync runs automatically before fetching if Auto Sync is ON
• Lock: bwenv logout runs bw lock

1Password

• CLI: op — Install
• Auth: System biometrics (op v2) or manual sign-in
• Secrets: Item fields within vaults. Field label = env var name, field value = env var value. Notes and OTP fields are skipped.
• Lock: bwenv logout runs op signout

Adding a Provider

bwenv’s provider system is extensible. To add a new provider:

1. Create a file in internal/provider/ (e.g. doppler.go)
2. Implement the Provider interface (including the Lock() method)
3. Call Register(&YourProvider{}) in an init() function
4. The provider automatically appears in the TUI picker and CLI flags

Folder Structure Recommendations

Organize secrets in your password manager by project and environment:

Vault / Folders
├── ProjectA - Development
├── ProjectA - Staging
├── ProjectA - Production
├── ProjectB - Development
└── Shared Tools

Use consistent field names across environments so you can switch between dev/staging/prod by just pointing bwenv at a different folder.

Security Notes

1. No secrets on disk — .envrc contains only an eval command with a session token, not actual secrets
2. Session tokens expire — Bitwarden sessions expire based on vault timeout settings
3. Lock when done — bwenv logout locks vaults and terminates sessions
4. .envrc in .gitignore — Never commit environment files to version control
5. Direnv approval — .envrc must be explicitly approved via direnv allow (or bwenv allow)

Troubleshooting

Session expired

bwenv login    # Re-authenticate and update .envrc

No secrets found / 0 variables loaded

• Bitwarden: Ensure items have custom fields (not just username/password)
• 1Password: Ensure items have fields with labels and values

direnv messages appearing

bwenv config    # Toggle "Show Direnv Output" to OFF

Or restart your shell after bwenv has added the DIRENV_LOG_FORMAT line.

Full diagnostic

bwenv status    # Shows everything at a glance