bitwarden.zsh

Zsh plugin for quickly accessing Bitwarden secrets with auto-completion, caching, and TOTP support — securely and efficiently.

Features

• Secure access to passwords and TOTP codes
• Fast item lookup with tab-completion
• Encrypted local cache of items (auto-refreshed every 6 hours)
• Uses your existing Bitwarden CLI session if available
• Minimal dependencies: bw, jq, oathtool (for TOTP)

---

Requirements

• Bitwarden CLI (bw)
• jq
• [oathtool] for TOTP functionality (installed by default on many systems)

---

Installation

Using Zinit

zinit wait lucid for \
  casonadams/bitwarden.zsh

Using Oh My Zsh

ZSH_CUSTOM="${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}"
git clone https://github.com/casonadams/bitwarden.zsh.git "$ZSH_CUSTOM/plugins/bitwarden.zsh"

then add it to your .zshrc:

plugins+=(bitwarden.zsh)

Setup Tips

Having issues?

Try removing old cache files:

rm -f /tmp/.bw_items_cache* /tmp/.bw_session

Usage

Retrieve a password

bwpass github.com/john@example.com

Or use interactive auto-complete:

bwpass <TAB>

Retrieve a TOTP code

bwtotp github.com/john@example.com

Or interactively auto-complete:

bwtotp <TAB>

Examples

# Copy password for AWS
bwpass aws.amazon.com/user@example.com

# Copy TOTP for GitHub
bwtotp github.com/user@example.com

# View available entries
bwpass <TAB>
bwtotp <TAB>

Troubleshooting

• Cache issues? Try: rm -f /tmp/.bw_*.