How to Install and Use bluetui in Linux for Interactive Terminal Bluetooth Device Management

Managing wireless headphones, mechanical keyboards, mice, and game controllers in Linux can be frustrating. GUI settings panels in desktop environments like GNOME or KDE are heavy and occasionally fail to handle obscure pairing passkeys, while the native command-line utility bluetoothctl requires remembering multi-step interactive commands (scan on, pair MAC, trust MAC, connect MAC). bluetui is a fast, keyboard-driven terminal user interface (TUI) written in Rust. It communicates directly with the BlueZ Linux Bluetooth stack via DBus, providing an intuitive, interactive curses-style dashboard to discover, pair, connect, and configure devices in seconds.

Why Choose bluetui Over bluetoothctl or GUI Panels?

bluetui combines the speed of terminal workflows with the visual clarity of modern TUI dashboards:

• Interactive Live Scanning: Sweeps 2.4 GHz Bluetooth frequencies dynamically, displaying nearby device names, signal strength (RSSI), battery percentages, and device classes in real time.
• One-Key Operations: Pair, connect, trust, block, or unpair accessories instantly using simple single-letter keyboard shortcuts rather than typing 48-bit hexadecimal MAC addresses.
• Clean Adapter Management: Easily switch between multiple onboard or USB Bluetooth adapters, toggle discoverability, and power radios on or off.
• Lightweight Footprint: Zero GUI dependencies. Operates seamlessly over SSH connections or in minimalist tiling window manager setups (i3, sway, bspwm, Hyprland).

Keybinding	Action	Operational Description
s	Toggle Scan	Starts or stops Bluetooth Low Energy (BLE) and classic device discovery
c	Connect / Disconnect	Toggles active wireless audio or input link to highlighted device
p	Pair Device	Initialises cryptographic pairing handshake and handles PIN authentication
t	Trust Device	Marks device as trusted for automatic reconnection upon powering on
d	Unpair / Delete	Removes device pairing credentials and removes it from the trusted cache
b	Block / Unblock	Prevents unwanted nearby accessories from initiating pairing requests
q	Quit	Exits the application cleanly and restores terminal cursor state

Installing bluetui on Linux

bluetui can be installed across modern Linux distributions via Cargo, precompiled release binaries, or distribution package managers:

Method 1: Installing via Cargo (Any Distribution)

If you have Rust and Cargo installed:

sudo apt update && sudo apt install -y build-essential libdbus-1-dev pkg-config
cargo install bluetui

Ensure ~/.cargo/bin is in your shell $PATH.

Method 2: Arch Linux (AUR)

yay -S bluetui-bin

Method 3: Downloading Precompiled GitHub Binaries

curl -LO https://github.com/pythops/bluetui/releases/latest/download/bluetui-linux-x86_64.tar.gz
tar -xzf bluetui-linux-x86_64.tar.gz
sudo mv bluetui /usr/local/bin/
bluetui --version

Step-by-Step: Pairing and Connecting Bluetooth Headphones

To pair and configure an accessory with bluetui:

1. Ensure the Bluetooth system daemon is running:

   sudo systemctl enable --now bluetooth.service

2. Launch the utility in your terminal:

   bluetui

3. Put your Bluetooth headphones or controller into physical pairing mode (usually holding the power button until an LED flashes).
4. In bluetui, press s to toggle on discovery scanning. Nearby accessories will populate the device list along with their signal bars.
5. Use the Up (↑) and Down (↓) arrow keys (or k and j) to highlight your target device.
6. Press p to pair with the device. If prompted for a PIN code or passkey confirmation, enter it at the bottom prompt.
7. Press t to mark the device as Trusted. This ensures your headphones automatically reconnect whenever you power them on in the future.
8. Press c to establish the active connection. The status indicator will transition to green: Connected: Yes.
9. Press s to stop background scanning and conserve battery.
10. Press q to exit bluetui. Your audio connection remains fully active in PulseAudio or PipeWire.

Troubleshooting Common bluetui Issues

• “No default controller available” Error: Indicates that Linux cannot communicate with your Bluetooth adapter. Check if your hardware is software-blocked using rfkill list, and unblock it with sudo rfkill unblock bluetooth.
• Permission Refused via DBus: Ensure your user account is a member of the bluetooth and netdev groups:

  sudo usermod -aG bluetooth $USER

  Log out and log back in for group permission changes to take effect.
• Audio Connected But No Sound: If headphones connect successfully in bluetui but sound continues playing through internal speakers, verify your PipeWire or WirePlumber routing using pavucontrol or wpctl status to set your headset as the default sink.