bwpy-tui

A powerful curses-based TUI wrapper around rbw (Rust Bitwarden CLI) with enhanced search, field management, and script integration capabilities.

Features

• 🎨 Beautiful TUI Interface: Clean, vim-like navigation with color-coded search
• 🔍 Advanced Search: Real-time filtering with visual feedback
• 🔐 OTP Support: Automatic TOTP detection and copying
• 📁 Field Management: Dropdown menus for additional fields with expand/collapse
• 👁️ Hidden Field Reveal: Hover to reveal hidden field values
• 📋 Smart Copying: Copy any field value to clipboard
• ❓ Help System: Comprehensive keymap reference (? key)
• 🔧 Script Integration: --stdout mode for automation
• 🎯 Robust: Proper error handling and bounds checking

Installation

Prerequisites

• Python 3.7+
• rbw (Rust Bitwarden CLI) installed and configured
• Clipboard program (wl-copy or xclip)

Install rbw

# Using cargo
cargo install rbw

# Or download from GitHub releases
# https://github.com/doy/rbw/releases

Install bwpy-tui

# Clone the repository
git clone https://github.com/yourusername/bwpy-tui.git
cd bwpy-tui

# Make executable
chmod +x bwpy-tui.py

# Optional: Install to PATH
sudo cp bwpy-tui.py /usr/local/bin/bwpy-tui

Usage

Interactive Mode (Default)

./bwpy-tui.py
# or
bwpy-tui

Script Integration Mode

./bwpy-tui.py --stdout

Custom Scroll Padding

# Use 3 items padding (tighter scrolling)
./bwpy-tui.py --scroll-padding 3

# Use 10 items padding (more relaxed scrolling)
./bwpy-tui.py --scroll-padding 10

# Combine with stdout mode
./bwpy-tui.py --stdout --scroll-padding 7

In stdout mode:

• Navigate and search normally
• Enter entry view and select any field (username, password, TOTP, etc.)
• Press y to copy the selected field
• The field value is printed to stdout and the application exits
• If copying a password and TOTP is available, TOTP is also copied to clipboard

Keybindings

Navigation

Key	Action
j/k	Move up/down
g/G	Go to top/bottom
Enter/l	Open entry

Search

Key	Action
/	Start search
Esc	Exit search

Entry View

Key	Action
y	Copy field
space	Reveal hidden field
l/Enter	Expand dropdown
h	Back to list

General

Key	Action
?	Show help
q	Quit

Field Types

Core Fields

• Username: Login username
• Password: Login password (hidden by default)
• TOTP: Time-based one-time password (if available)

Additional Fields

• Custom Fields: Any additional fields from your Bitwarden entries
• Hidden Fields: Fields marked as type: "hidden" are masked by default
• Dropdown: Additional fields are organized in an expandable dropdown

Examples

Basic Usage

# Start the TUI
bwpy-tui

# Search for entries containing "github"
# Press /, type "github", press Enter

# Copy password
# Navigate to entry, press Enter, press y on password field

Script Integration

#!/bin/bash
# Get field value and auto-copy TOTP if password
field_value=$(bwpy-tui --stdout)
echo "Selected field value: $field_value"
# If it was a password, TOTP is also in clipboard

Advanced Field Management

# In entry view:
# 1. Navigate to "Other" dropdown
# 2. Press l/Enter to expand
# 3. Navigate through additional fields
# 4. Press space to reveal hidden field values
# 5. Press y to copy any field

Configuration

Scroll Padding

The --scroll-padding flag controls how many items are kept visible around the cursor when scrolling:

• Default: 5 items
• Lower values (1-3): Tighter scrolling, cursor moves closer to edges
• Higher values (7-10): More relaxed scrolling, cursor stays more centered
• Range: 1-20 (recommended)

Clipboard Programs

bwpy-tui automatically detects and uses:

• wl-copy (Wayland)
• xclip (X11)

rbw Configuration

Ensure rbw is properly configured:

# Login to Bitwarden
rbw login

# Test access
rbw ls

Troubleshooting

Common Issues

"rbw not found in PATH"

• Install rbw: cargo install rbw
• Ensure rbw is in your PATH

"Clipboard program not found"

• Install wl-copy (Wayland) or xclip (X11)
• Wayland: sudo pacman -S wl-clipboard
• X11: sudo pacman -S xclip

TOTP not working

• Ensure TOTP is enabled in Bitwarden
• Check that rbw code <entry> works manually

Search not working

• Press / to enter search mode
• Type your search term
• Press Enter or Esc to exit search

Debug Mode

For debugging, you can modify the script to add verbose output or check the rbw integration manually:

# Test rbw integration
rbw ls --fields name
rbw get "entry-name" --raw
rbw code "entry-name"

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is open source. Please check the license file for details.

Acknowledgments

• Built on top of rbw by doy
• Inspired by vim-like TUI applications
• Uses Python's curses library for terminal interface

Changelog

v1.0.0

• Initial release
• Basic TUI functionality
• Search and navigation
• Field management with dropdowns
• OTP support
• Help system
• Script integration mode (--stdout)

---

Note: This tool is a wrapper around rbw. Make sure to keep rbw updated and properly configured for the best experience.