tmux-bitwarden

Search and access your Bitwarden vault directly inside tmux using fuzzy search.

Quickly search login items and paste credentials without leaving your terminal.

tmux-bitwarden-demo.mp4

Features

• 🔍 Fuzzy search Bitwarden items with fzf
• 👀 Preview username and URIs before selecting
• 🔐 Secure vault access through the Bitwarden CLI
• 🔁 Automatic re-authentication on session expiration
• ⚡ Fast search with optional caching
• ⌨️ Keyboard-driven workflow
• 📋 Paste or copy credentials (username, password, TOTP)
• 🔄 Refresh cache without leaving the selector
• 🖥 Popup or split pane interface

Requirements

You need the following tools installed:

• Bitwarden CLI
• jq
• fzf
• Bash >= 4
• tmux >= 3.0

Installation

Using Tmux Plugin Manager (recommended)

Add the plugin to your .tmux.conf:

set -g @plugin 'Alkindi42/tmux-bitwarden'

Then, install it:

prefix + I

Usage

Press: prefix + b to open the Bitwarden selector.

You can then:

• search your vault items
• preview item details
• paste or copy credentials

Key Bindings

Available inside the selector:

Key	Action
Enter	Paste password into the active pane
Ctrl-y	Copy password to clipboard
Ctrl-u	Paste username into the active pane
Alt-u	Copy username to clipboard
Ctrl-r	Refresh cached items
Alt-t	Copy TOTP to clipboard
Ctrl-t	Paste TOTP into the active pane

Authentication

Before using the plugin, you only need to log in to Bitwarden using the CLI:

bw login

No manual BW_SESSION export is required.

The plugin automatically:

• reuses your existing Bitwarden session when available
• prompts for unlock only when necessary
• retries operations transparently if the session expires

Configuration

All options are optional.

Default configuration

The plugin works out of the box with the following defaults:

Option	Default
@bw-key	b
@bw-ui	popup
@bw-ui-split-size	20
@bw-ui-popup-width	80%
@bw-ui-popup-height	80%
@bw-cache	true
@bw-cache-ttl	86400
@bw-cache-file	~/.cache/tmux-bitwarden/items.json

---

Example configuration

set -g @bw-key 'b'
set -g @bw-ui 'popup'
set -g @bw-cache 'true'
set -g @bw-cache-ttl '86400'

UI options

Option	Description
@bw-ui	popup or split
@bw-ui-split-size	Height of the split pane
@bw-ui-popup-width	Popup width (%)
@bw-ui-popup-height	Popup height (%)

Example:

set -g @bw-ui 'split'
set -g @bw-ui-split-size '20'
set -g @bw-ui-popup-height '90'

Cache options

Option	Description
@bw-cache	Enable or disable caching
@bw-cache-ttl	Cache duration in seconds (-1 to never expire)
@bw-cache-file	Cache file location

set -g @bw-cache 'true'
set -g @bw-cache-ttl '86400'

With -1, cached items never expire automatically.
You can refresh the cache anytime inside the selector with Ctrl-r.

Security

• Passwords are never stored in the cache
• Only metadata (name, username, URIs) is cached
• Passwords are retrieved only when required
• Vault access is handled by the Bitwarden CLI session

License

This project is licensed under the MIT License.