Skip to main content
Bitwarden CLI (bw) is the primary secrets manager for this dotfiles setup. It stores SSH keys, age encryption keys, and AWS credentials securely in your Bitwarden vault.

​
Installation

The bootstrap script automatically installs Bitwarden CLI using either snap or npm:
bootstrap.sh:27-37
# 3. Install Bitwarden CLI
if ! command -v bw >/dev/null 2>&1; then
    if command -v snap >/dev/null 2>&1 && snap version >/dev/null 2>&1; then
        echo "Installing Bitwarden CLI via snap..."
        sudo snap install bw
    else
        echo "Installing Bitwarden CLI via npm..."
        sudo apt-get install -y nodejs npm
        sudo npm install -g @bitwarden/cli
    fi
fi

​
Login and Unlock Flow

During bootstrap, the script checks Bitwarden’s authentication status and performs login/unlock as needed:
bootstrap.sh:51-62
# 5. Bitwarden Login & Unlock
if bw status | grep -q '"status":"unauthenticated"'; then
    echo "Logging into Bitwarden..."
    bw login
fi

if bw status | grep -q '"status":"locked"'; then
    echo "Unlocking Bitwarden..."
    BW_SESSION=$(bw unlock --raw)
    export BW_SESSION
    bw sync
fi

​
How It Works

  1. Authentication Check: bw status returns the current vault status
  2. Login: If unauthenticated, prompts for email and master password
  3. Unlock: If locked, prompts for master password and exports session token
  4. Sync: Synchronizes vault with Bitwarden servers

​
Session Management

After bootstrap, use the bw_unlock() function for session management:
dot_bash_functions:20-24
# Bitwarden session management
bw_unlock() {
    export BW_SESSION=$(bw unlock --raw)
    echo "Bitwarden vault unlocked"
}

​
Usage

# Unlock your vault and export session token
bw_unlock

# Check vault status
bw_status

# Manually retrieve a secret
bw get item "my-secret-name"
The BW_SESSION environment variable must be exported for chezmoi to access Bitwarden during chezmoi apply.

​
Chezmoi Integration

Bitwarden is configured in chezmoi’s config with auto-unlock:
.chezmoi.toml.tmpl:41-43
[bitwarden]
    command = "bw"
    unlock = "auto"
This enables chezmoi template functions:
  • bitwarden "item" "name" - Retrieve item notes
  • bitwardenFields "item" "name" - Retrieve custom fields

​
Common Operations

​
Check Vault Status

bw status
Returns JSON with current authentication state: 
{
  "status": "locked",
  "lastSync": "2026-03-04T10:30:00.000Z",
  "userEmail": "[email protected]"
}

​
Lock Vault

bw lock
unset BW_SESSION

​
Sync Vault

bw sync

​
Security Best Practices

  • Never commit BW_SESSION tokens to git
  • Lock your vault when leaving your machine: bw lock
  • Use session timeout for automatic locking
  • Store the master password securely (password manager, not in dotfiles)

​
Troubleshooting

​
Session Expired

If you get authentication errors: 
bw_unlock  # Re-unlock and export session

​
Sync Issues

If items aren’t found: 
bw sync  # Force sync with server

​
Permission Denied

Ensure BW_SESSION is exported: 
echo $BW_SESSION  # Should output a token

Build docs developers (and LLMs) love

Get started for freeTalk to us