CLI Reference

Commands

bwenv init

Initialize secrets for the current project with manual folder selection.

bwenv init [OPTIONS]

Behavior:

1. Prompts for Bitwarden folder name
2. Unlocks Bitwarden vault (if needed)
3. Loads all custom fields from items in the specified folder
4. Creates .envrc file with environment variables
5. Instructions for activating with direnv allow

Example:

$ bwenv init
Enter Bitwarden folder name: Production API Keys
Unlocking Bitwarden vault...
Loading secrets from folder: Production API Keys
Found 5 items with 12 environment variables
Created .envrc with environment variables
Run 'direnv allow' to activate environment variables

---

bwenv interactive

Select Bitwarden folder interactively from a numbered list.

bwenv interactive [OPTIONS]

Behavior:

1. Lists all Bitwarden folders with numbers
2. Prompts for folder selection by number
3. Loads secrets and creates .envrc file
4. Same result as init but with folder selection UI

Example:

$ bwenv interactive
Available Bitwarden folders:
1) Development Secrets
2) Staging Environment
3) Production API Keys
4) Shared Tools
Enter folder number (1-4): 3
Loading secrets from folder: Production API Keys
...

---

bwenv test

Test installation and verify all dependencies.

bwenv test [OPTIONS]

Checks:

• Bitwarden CLI installation and login status
• direnv installation and shell integration
• jq availability
• bwenv helper script installation
• File permissions and PATH configuration

Example:

$ bwenv test
✓ Bitwarden CLI: Found (version 2024.1.0)
✓ Bitwarden Login: Authenticated
✓ direnv: Found (version 2.32.2)
✓ direnv Hook: Configured in shell
✓ jq: Found (version 1.6)
✓ Helper Script: Installed at ~/.config/direnv/lib/bitwarden_folders.sh
✓ PATH: ~/.local/bin is in PATH
All checks passed!

---

bwenv remove

Remove .envrc file from the current directory.

bwenv remove [OPTIONS]

Behavior:

• Deletes .envrc file if it exists
• Creates backup as .envrc.bak before deletion
• Confirms removal with user

Example:

$ bwenv remove
Removing .envrc from current directory...
Backup created: .envrc.bak
.envrc removed successfully

---

bwenv --help

Show help information and usage examples.

bwenv --help
bwenv -h

---

bwenv --version

Display version information.

bwenv --version
bwenv -v

Global Options

--debug[=LEVEL], -d

Enable debug output with optional level specification.

• --debug or --debug=2: Full debug (show steps and secret values)
• --debug=1: Show steps only, hide secret values
• No flag: Default behavior (steps only, hide secrets)

Examples:

bwenv --debug init          # Full debug (level 2)
bwenv --debug=1 init       # Steps only (level 1)
bwenv -d interactive       # Full debug (level 2)

--quiet, -q

Quiet mode - minimal output, errors only.

Examples:

bwenv --quiet init         # Minimal output
bwenv -q interactive      # Minimal output

Exit Codes

• 0: Success
• 1: General error
• 2: Missing dependencies
• 3: Bitwarden authentication failure
• 4: direnv not configured
• 5: File permission error

Environment Variables

Input Variables

• BWENV_DEBUG: Set debug level (0=silent, 1=steps, 2=full)
• BW_SESSION: Bitwarden session token (auto-managed)

Output Variables

All custom fields from Bitwarden items become environment variables:

# Example Bitwarden item custom fields:
DATABASE_URL=postgresql://...
API_KEY=sk_test_...
JWT_SECRET=your-jwt-secret

# Available after 'direnv allow':
echo $DATABASE_URL
echo $API_KEY
echo $JWT_SECRET

File Operations

Created Files

• .envrc: Main environment file for direnv
• .envrc.bak: Backup of previous .envrc (if exists)

File Format

Generated .envrc files use this format:

#!/usr/bin/env bash
# Generated by bwenv from Bitwarden folder: "Folder Name"
# Generated on: 2024-01-15 10:30:00

# Load secrets from Bitwarden folder
load_bitwarden_folder "Folder Name"

Integration Examples

Shell Aliases

Add to your shell config (.bashrc, .zshrc):

# Quick aliases
alias bwi='bwenv interactive'
alias bwt='bwenv test'
alias bwr='bwenv remove'

# Debug aliases
alias bwd='bwenv --debug'
alias bwq='bwenv --quiet'

Git Hooks

Pre-commit hook to ensure no secrets in git:

.git/hooks/pre-commit

#!/bin/sh
if [ -f .envrc ]; then
    echo "Warning: .envrc file found"
    echo "Make sure .envrc is in .gitignore"
    grep -q "\.envrc" .gitignore || {
        echo "Adding .envrc to .gitignore"
        echo ".envrc" >> .gitignore
    }
fi

Makefile Integration

Add to your project Makefile:

.PHONY: secrets secrets-dev secrets-prod

secrets:
  @bwenv interactive
  @direnv allow

secrets-dev:
  @echo "Development Secrets" | bwenv init
  @direnv allow

secrets-prod:
  @echo "Production Secrets" | bwenv init
  @direnv allow

Error Messages

Common Errors

“Bitwarden CLI not found”

Error: Bitwarden CLI not found
Install with: npm install -g @bitwarden/cli

“Not logged into Bitwarden”

Error: Not logged into Bitwarden
Run: bw login

“direnv not configured”

Error: direnv hook not found in shell config
Add to ~/.bashrc: eval "$(direnv hook bash)"

“Folder not found”

Error: Bitwarden folder 'Invalid Folder' not found
Available folders:
- Development Secrets
- Production API Keys

Debug Output Example

With --debug=2:

$ bwenv --debug=2 init
[DEBUG] Checking Bitwarden status...
[DEBUG] Bitwarden status: unlocked
[DEBUG] Folder name: Production API Keys
[DEBUG] Found folder ID: abc-123-def
[DEBUG] Loading items from folder...
[DEBUG] Found 3 items:
[DEBUG]   - API Configuration
[DEBUG]   - Database Settings
[DEBUG]   - Third-party Keys
[DEBUG] Processing custom fields...
[DEBUG] API_KEY=sk_test_1234567890abcdef
[DEBUG] DATABASE_URL=postgresql://user:pass@host:5432/db
[DEBUG] REDIS_URL=redis://localhost:6379
[DEBUG] JWT_SECRET=your-secret-key-here
[DEBUG] Writing .envrc file...
[DEBUG] Created .envrc with 4 environment variables