Configuration

Environment Variables

BWENV_DEBUG

Controls the debug output level:

• BWENV_DEBUG=0: Silent mode (errors only)
• BWENV_DEBUG=1: Show processing steps, hide secret values (default)
• BWENV_DEBUG=2: Show processing steps and actual secret values (full debug)

# Set for single command
BWENV_DEBUG=2 bwenv init

# Set for direnv operations
BWENV_DEBUG=1 direnv allow

# Export for session
export BWENV_DEBUG=2
bwenv interactive

BW_SESSION

Bitwarden session token (managed automatically by bwenv):

# Typically set automatically when you unlock Bitwarden
export BW_SESSION="your-session-token"

Command-Line Options

Global Options

• --debug[=LEVEL], -d: Enable debug mode (level 1 or 2)
• --quiet, -q: Quiet mode (minimal output)
• --help, -h: Show help information
• --version, -v: Show version information

# Debug modes
bwenv --debug init          # Level 2 (full debug)
bwenv --debug=1 init       # Level 1 (steps only)
bwenv --debug=2 init       # Level 2 (full debug)

# Quiet mode
bwenv --quiet init
bwenv -q init

# Help and version
bwenv --help
bwenv --version

File Locations

Configuration Files

• Helper Script: ~/.config/direnv/lib/bitwarden_folders.sh
• CLI Executable: ~/.local/bin/bwenv (Unix/macOS) or %USERPROFILE%\.local\bin\bwenv.bat (Windows)

Project Files

• Environment File: .envrc (created in project directory)
• Backup: .envrc.bak (created automatically if .envrc exists)

Bitwarden Integration

Required Setup

1. Bitwarden CLI installed: bw --version should work
2. Logged in: bw login (one-time setup)
3. Folder organization: Secrets stored in organized folders

Folder Structure Recommendations

Bitwarden Vault
├── Personal/
├── Work Projects/
│   ├── ProjectA - Development
│   ├── ProjectA - Staging
│   ├── ProjectA - Production
│   └── ProjectB - Development
└── Shared Tools/
    ├── CI/CD Secrets
    └── Development Tools

Custom Fields Format

Bitwarden items should use Custom Fields for environment variables:

Example Item: “Database Configuration”

• Name: Database Configuration
• Custom Fields:
  • DATABASE_URL → postgresql://user:pass@localhost:5432/myapp
  • DB_POOL_SIZE → 20
  • DB_TIMEOUT → 30
  • REDIS_URL → redis://localhost:6379

direnv Integration

Required Setup

1. direnv installed: direnv --version should work
2. Shell hook configured:

   # Add to ~/.bashrc, ~/.zshrc, etc.
   eval "$(direnv hook bash)"   # for bash
   eval "$(direnv hook zsh)"    # for zsh

Helper Script

The bitwarden_folders.sh helper script is installed to ~/.config/direnv/lib/ and provides:

• load_bitwarden_folder(): Main function to load secrets
• Session management
• Error handling
• Debug output

Makefile Commands

Available commands for project management:

make help         # Show all available commands
make install      # Install bwenv CLI and helper scripts
make setup-path   # Add ~/.local/bin to PATH (Linux/macOS)
make uninstall    # Remove bwenv CLI and helper scripts
make test         # Run installation tests

Security Configuration

Session Management

• Auto-unlock: bwenv will prompt for master password if needed
• Session timeout: Respects Bitwarden CLI session timeout
• Manual lock: Use bw lock to manually lock session

File Permissions

bwenv creates .envrc files with restricted permissions:

# .envrc permissions (readable by owner only)
-rw------- 1 user user .envrc

Best Practices

1. Lock when done: Always bw lock after work
2. Separate environments: Use different folders for dev/staging/prod
3. Regular rotation: Rotate secrets regularly
4. Team access: Use Bitwarden Organizations for team sharing
5. Version control: Add .envrc to .gitignore

Troubleshooting Configuration

Common Issues

1. direnv not loading:

   # Check direnv hook is in shell config
   grep direnv ~/.bashrc ~/.zshrc
   
   # Check direnv status
   direnv status

2. Bitwarden session issues:

   # Check status
   bw status
   
   # Re-login if needed
   bw login
   
   # Unlock vault
   bw unlock

3. PATH issues:

   # Check if bwenv is in PATH
   which bwenv
   
   # Add to PATH manually
   export PATH="$HOME/.local/bin:$PATH"

Debug Commands

# Test complete setup
bwenv test

# Check Bitwarden folders
bw list folders

# Debug bwenv with full output
BWENV_DEBUG=2 bwenv interactive

# Check direnv configuration
direnv status

# Manual helper script test
source ~/.config/direnv/lib/bitwarden_folders.sh

Advanced Configuration

Custom Installation Paths

If you need different installation paths, manually copy files:

# Custom CLI location
cp setup/bwenv /your/custom/bin/path/

# Custom helper location
cp setup/bitwarden_folders.sh /your/custom/direnv/lib/

Integration with CI/CD

For automated environments:

# Use service account or API key
export BW_CLIENTID="your-client-id"
export BW_CLIENTSECRET="your-client-secret"

# Use quiet mode
bwenv --quiet init

# Bypass interactive prompts
echo "folder-name" | bwenv init