bluetooth-tui

A Terminal User Interface (TUI) for managing Bluetooth connections on macOS, built with Go and wrapping around blueutil.

Features

• 📱 List all paired Bluetooth devices
• 🔗 Connect/disconnect devices
• 🔵 Unpair devices
• 🔄 Refresh device list
• ⌨️ Intuitive keyboard navigation

Prerequisites

• macOS
• blueutil installed (can be installed via Homebrew: brew install blueutil)
• Go 1.21+ (for building from source)

Installation

Option 1: Download Pre-built Binary (Recommended)

Download the latest release from the Releases page:

1. Download the appropriate binary for your system (macOS Intel/Apple Silicon)
2. Extract the binary and move it to a directory in your PATH:

   # For example, to /usr/local/bin
   sudo mv bluetooth-tui /usr/local/bin/

3. Run the application:

   bluetooth-tui

Option 2: Install via Go

go install github.com/MatthewMyrick/bluetooth-tui@latest

After installation, you can run the application from anywhere:

bluetooth-tui

Option 3: Install via Homebrew (Coming Soon)

brew tap MatthewMyrick/bluetooth-tui
brew install bluetooth-tui

Option 4: Build from Source

1. Clone this repository:

   git clone https://github.com/MatthewMyrick/bluetooth-tui.git
   cd bluetooth-tui

2. Build the application:

   go build -o bluetooth-tui

3. Run the application:

   ./bluetooth-tui

Usage

Keyboard Shortcuts

• ↑/k - Move up in the device list
• ↓/j - Move down in the device list
• c - Connect to the selected device
• d - Disconnect from the selected device
• u - Unpair the selected device
• r - Refresh the device list
• q - Quit the application

Device Status Icons

• 🔗 Connected device
• 🔵 Paired but not connected device
• 📱 Other devices

How it Works

The application uses the blueutil command-line tool to interact with macOS Bluetooth functionality:

• Lists paired devices using blueutil --paired --format json
• Gets connected devices using blueutil --connected --format json
• Connects to devices using blueutil --connect <address>
• Disconnects devices using blueutil --disconnect <address>
• Unpairs devices using blueutil --unpair <address>

The TUI is built using Bubble Tea framework with Bubbles components for a rich terminal experience.

Dependencies

• github.com/charmbracelet/bubbletea - TUI framework
• github.com/charmbracelet/bubbles - TUI components
• github.com/charmbracelet/lipgloss - Styling

Troubleshooting

If you encounter permission issues, make sure your terminal application has the necessary permissions to access Bluetooth functionality in macOS System Preferences > Security & Privacy > Privacy > Bluetooth.