Usage Examples

Basic Usage

Initialize with Manual Folder Entry

cd /your/project
bwenv init
# Enter folder name when prompted: "Production Secrets"
direnv allow

Interactive Folder Selection

cd /your/project
bwenv interactive
# Select folder by number from the list
direnv allow

Debug Modes

bwenv supports different debug levels to help you understand what’s happening:

Default Mode (Steps Only)

bwenv init
# Shows: Processing steps, hides secret values

Silent Mode

bwenv --quiet init
# or
bwenv -q init
# Shows: Minimal output, errors only

Full Debug Mode

bwenv --debug=2 init
# or
bwenv --debug init
# Shows: Processing steps AND actual secret values

Debug with direnv

# Set debug level for direnv operations
BWENV_DEBUG=1 direnv allow   # Steps only
BWENV_DEBUG=2 direnv allow   # Full debug
BWENV_DEBUG=0 direnv allow   # Silent

Real-World Examples

Example 1: Web Development Project

# Navigate to your web project
cd ~/projects/my-webapp

# Use interactive mode to select "Web App Secrets" folder
bwenv interactive
# Select: 3) Web App Secrets

# Activate environment
direnv allow

# Your secrets are now available
echo $DATABASE_URL
echo $API_KEY
echo $JWT_SECRET

# Start your development server
npm run dev

Example 2: Multiple Environments

# Development environment
cd ~/projects/myapp-dev
bwenv init  # Select "MyApp - Development"
direnv allow

# Staging environment
cd ~/projects/myapp-staging
bwenv init  # Select "MyApp - Staging"
direnv allow

# Production deployment
cd ~/projects/myapp-prod
bwenv init  # Select "MyApp - Production"
direnv allow

Example 3: CI/CD Pipeline

# In your CI/CD script
cd $WORKSPACE

# Use quiet mode for automated environments
bwenv --quiet init --folder "CI/CD Secrets"
direnv allow

# Run your deployment
./deploy.sh

Advanced Usage

Custom Environment Variables

Your Bitwarden items should have custom fields that will become environment variables:

Bitwarden Item: “Database Config”

• Custom Field: DATABASE_URL → postgresql://user:pass@host:5432/db
• Custom Field: DB_POOL_SIZE → 20
• Custom Field: DB_TIMEOUT → 30

After running bwenv init and direnv allow:

echo $DATABASE_URL     # postgresql://user:pass@host:5432/db
echo $DB_POOL_SIZE     # 20
echo $DB_TIMEOUT       # 30

Working with Teams

1. Shared Folder Structure: Organize secrets in Bitwarden folders by project/environment
2. Consistent Naming: Use consistent custom field names across team
3. Documentation: Document which folder contains which secrets

# Team folder structure example:
# - "ProjectX - Development"
# - "ProjectX - Staging"
# - "ProjectX - Production"
# - "Shared Tools"

# Each team member can use:
bwenv interactive  # Select appropriate folder

Debugging Issues

# Test your setup
bwenv test

# Check what's in your .envrc
cat .envrc

# Debug direnv loading
BWENV_DEBUG=2 direnv allow

# Verify Bitwarden session
bw status

# List available folders
bw list folders

Cleanup

Remove Secrets from Project

bwenv remove
# Removes .envrc file from current directory

Clear Bitwarden Session

bw lock
# Locks your Bitwarden session

Tips and Best Practices

Security Best Practices

1. Always lock Bitwarden when done: bw lock
2. Use specific folders: Don’t put everything in one folder
3. Regular rotation: Rotate secrets regularly
4. Team access: Use Bitwarden organizations for team access

Development Workflow

1. Per-environment folders: Separate dev/staging/prod secrets
2. Consistent field names: Use same variable names across environments
3. Version control: Add .envrc to .gitignore
4. Team onboarding: Document which folders new team members need

Troubleshooting Workflow

# 1. Test installation
bwenv test

# 2. Check Bitwarden status
bw status

# 3. List folders (debug what's available)
bw list folders

# 4. Try with full debug
bwenv --debug=2 interactive

# 5. Check direnv
direnv status