btui

btui - Bluetooth Device Manager via D-Bus

    ██████╗ ████████╗██╗   ██╗██╗
    ██╔══██╗╚══██╔══╝██║   ██║██║
    ██████╔╝   ██║   ██║   ██║██║
    ██╔══██╗   ██║   ██║   ██║██║
    ██████╔╝   ██║   ╚██████╔╝██║
    ╚═════╝    ╚═╝    ╚═════╝ ╚═╝
    ──────────────────────────────────
    Bluetooth Device Manager for Linux

A modern, terminal-based Bluetooth device manager for Linux
Interfaces directly with BlueZ via D-Bus • Built with Go and Bubble Tea

Demo

Features

• Smart Search - Filter devices by name or MAC address in real-time
• Quick Connect - One-key connection (pair + trust + connect automatically)
• Real-time Discovery - Auto-scan mode
• Device Management - Pair, connect, disconnect, trust, and remove devices
• Rich Information - RSSI signal strength, battery level, device type icons
• Adaptive UI - Centered layout that scales with terminal size
• ⌨Keyboard-Driven - Fast, efficient navigation without mouse
• Smart Sorting - Sort by connection status or alphabetically

Installation

Requirements

• OS: Linux with BlueZ stack
• Go: 1.24 or higher
• D-Bus: System D-Bus daemon running

From Source

# Clone the repository
git clone https://github.com/0x0FACED/btui.git
cd btui

# Install dependencies
go mod download

# Build
go build -o btui

# Run
./btui

Install with Go

go install github.com/0x0FACED/btui@latest

Usage

Keyboard Shortcuts

Quick Actions

• Enter - Quick Connect (automatically pair → trust → connect). Sometimes it's not connects fully - try to press Enter again.
• f - Toggle search mode (filter by name or address)
• Esc - Exit search mode (clear filter)

Scanning

• s - Scan once (5 seconds)
• a - Toggle auto-scan mode (continuous with ⠋ spinner)
• r - Refresh device list

Device Operations

• ↑/↓ or j/k - Navigate device list
• p - Pair selected device
• c - Connect to selected device
• d - Disconnect from selected device
• t - Trust selected device
• x - Remove selected device

View

• o - Change sort order (Status/Name)

Application

• q or Ctrl+C - Quit

Workflow Examples

Quick Connect (Recommended)

1. Press 's' to scan (or 'a' for auto-scan)
2. Navigate to device with ↑/↓
3. Press Enter
   → Automatically pairs, trusts, and connects!

Search and Connect

1. Press 'f' to open search
2. Type device name (e.g., "sony") or MAC address
3. Press Enter
   → Device is filtered and connected automatically

Monitor Devices

1. Press 'a' to enable auto-scan
2. Watch devices appear/disappear in real-time
3. RSSI and battery update continuously
4. Press 'a' again to disable

Manual Step-by-Step

1. Select device with ↑/↓
2. Press 'p' to pair
3. Press 't' to trust
4. Press 'c' to connect

Remove Device

1. Navigate to paired device
2. Press 'd' to disconnect (if connected)
3. Press 'x' to remove

Device Icons

• 🎧 Audio (headphones, headsets)
• 🔊 Speakers
• 🖱️ Mouse
• ⌨️ Keyboard
• 📱 Phone
• 💻 Computer
• 🎮 Game controller
• 📟 Generic device

Status Indicators

• 🔗 Connected - Device is connected and active
• 🔒 Paired - Device is paired but not connected
• ✅ Trusted - Device is trusted for auto-connect
• 📡 Discovered - Device found but not paired

Tech Stack

• TUI Framework: Bubble Tea - The Elm Architecture for Go
• Components: Bubbles - Table, Spinner, TextInput
• Styling: Lipgloss - Terminal styling
• Bluetooth: go-bluetooth - Go bindings for BlueZ
• D-Bus: godbus/dbus - Native D-Bus bindings

Configuration

btui works out-of-the-box with BlueZ defaults. No configuration file needed.

Bluetooth Agent

The application automatically:

• Registers a Bluetooth agent for pairing
• Handles PIN codes, passkeys, and confirmations
• Auto-approves service authorizations (A2DP, HFP, etc.)
• Powers on adapter if needed
• Cleans up on exit

Auto Features

• Auto-pair: Enter key triggers full pairing sequence
• Auto-trust: Devices are automatically trusted after pairing
• Auto-refresh: Device list updates every second
• Auto-clear: Status messages clear after 3-5 seconds

Troubleshooting

Common Issues

"Device not paired"

• Use Enter for automatic pairing, or press p first

"Cannot remove discovered device"

• Only paired/trusted devices can be removed
• Discovery-only devices disappear when out of range

"Disconnect first before removing"

• Active connections must be disconnected with d before removal

"Pairing failed"

• Ensure device is in pairing mode
• Check if device is already paired with another system
• Try removing and re-pairing

Permissions

btui requires D-Bus access to BlueZ. If you encounter permission errors:

# Check if user is in bluetooth group
groups $USER

# Add user to bluetooth group if needed
sudo usermod -aG bluetooth $USER

# Re-login for changes to take effect

Debug Mode

Run with stderr redirected to see detailed logs:

./btui 2>btui.log

# In another terminal, watch logs
tail -f btui.log

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• BlueZ - Official Linux Bluetooth stack
• Charm - Beautiful TUI libraries (Bubble Tea, Bubbles, Lipgloss)
• go-bluetooth - Go bindings for BlueZ
• D-Bus - Inter-process communication

Contact

• GitHub: @0x0FACED
• Telegram: @pick1e_morty
• Issues: GitHub Issues

Made with ❤️ Go and Charm