Usage Examples

Interactive Setup

The primary way to use bwenv is through the interactive TUI:

cd /your/project
bwenv init

This walks you through:

1. Provider selection — choose Bitwarden or 1Password (auto-detects available CLIs)
2. Authentication — master password, biometrics, or existing session
3. Folder/vault selection — browse, search, and filter with arrow keys
4. Preview — see which variables will be exported
5. Generate .envrc — auto-approved via direnv

Then trigger direnv:

cd .    # Reload environment
echo $YOUR_SECRET_VARIABLE

Non-Interactive Export

For CI/CD pipelines, scripts, or advanced usage:

# Output "export KEY=VALUE" lines to stdout
bwenv export --provider bitwarden --folder "MySecrets"

# Load directly into your shell
eval "$(bwenv export --provider bitwarden --folder "MySecrets")"

# Works with 1Password too
eval "$(bwenv export --provider 1password --folder "Production")"

Re-authenticate (Session Expired)

When your vault session expires, use bwenv login instead of re-running bwenv init:

bwenv login

This detects the provider from your existing .envrc, re-authenticates, updates the session token, and auto-approves — skipping provider and folder selection entirely.

Alias: bwenv auth works too.

Configure Preferences

bwenv config

Interactive settings editor to toggle:

Setting	Default	Description
Show Emoji	ON	Display emoji icons in output
Show Direnv Output	OFF	Show/hide direnv’s loading/unloading messages
Show Export Summary	ON	Show the boxed summary when secrets are loaded
Auto Sync	ON	Automatically sync vault before fetching (Bitwarden)

Settings persist to ~/.config/bwenv/config.json.

Status and Diagnostics

bwenv status

Shows a comprehensive overview:

• Current directory and .envrc info (provider, folder)
• direnv installation and hook status
• Provider CLI availability and active sessions
• Relevant environment variables (masked for security)
• Current config preferences

Lock Vaults / Logout

bwenv logout

Terminates all active provider sessions:

• Bitwarden — runs bw lock
• 1Password — runs op signout
• Shows any lingering session variables and how to clear them

Remove Secrets

bwenv remove

Deletes the .envrc file from the current directory.

Allow / Disallow

bwenv allow       # Approve .envrc for direnv
bwenv disallow    # Revoke direnv approval

Real-World Examples

Web Development Project

cd ~/projects/my-webapp

# Interactive setup
bwenv init
# Select "Bitwarden" → Enter master password → Select "Web App Secrets"

# Secrets are loaded
echo $DATABASE_URL
echo $API_KEY
npm run dev

Multiple Environments

# Development
cd ~/projects/myapp-dev
bwenv init    # Select "MyApp - Development" folder

# Staging
cd ~/projects/myapp-staging
bwenv init    # Select "MyApp - Staging" folder

# Each directory loads its own set of secrets automatically

CI/CD Pipeline (Bitwarden)

# Set session token from CI secrets
export BW_SESSION="${{ secrets.BW_SESSION }}"

# Load secrets non-interactively
eval "$(bwenv export --provider bitwarden --folder "Production")"

# Deploy
./deploy.sh    # $DB_URL, $API_KEY, etc. are available

CI/CD Pipeline (1Password)

# Set service account token from CI secrets
export OP_SERVICE_ACCOUNT_TOKEN="${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}"

# Load secrets non-interactively
eval "$(bwenv export --provider 1password --folder "Production")"

./deploy.sh

How Secrets Are Structured

Bitwarden

bwenv reads custom fields from items in a folder. Each custom field becomes one environment variable.

Create items in the Bitwarden web vault or app:

1. Create a Secure Note or Login item
2. Place it in a folder (e.g. “My Project Secrets”)
3. Add Custom Fields: field name = env var name, value = env var value

1Password

bwenv reads item fields from items in a vault. The field label becomes the env var name.

Create items in the 1Password app or CLI:

1. Create an item in a vault
2. Add fields with labels like DB_HOST, API_KEY, etc.

Notes and OTP fields are skipped.

Tips and Best Practices

1. Use bwenv login for expired sessions — faster than bwenv init
2. Separate folders per environment — dev, staging, production
3. Consistent field names — use the same env var names across environments
4. Add .envrc to .gitignore — never commit secrets
5. Use bwenv status to diagnose issues — checks everything at a glance
6. Lock vaults when done — bwenv logout for security