blueutil - macOS Bluetooth Command-Line Management Tool

Application Overview

blueutil is a powerful and lightweight macOS command-line tool designed specifically for managing and controlling the system's Bluetooth functionality. With simple terminal commands, users can easily perform various Bluetooth operations without needing to open the cumbersome System Preferences interface.

Core Features

1. Bluetooth Power Management

• Query the current on/off status of the Bluetooth module
• Turn Bluetooth power on or off with a single command
• Output concise status codes (1=on, 0=off)

2. Visibility Control

• Check whether the Bluetooth device is discoverable
• Dynamically toggle discoverability status
• Synchronized management with power state

3. Device Management

• List Paired Devices: Quickly view all paired Bluetooth devices
• Scan Nearby Devices: Search for available Bluetooth devices within range (default: 10 seconds)
• Show Recently Used Devices: View history of recently connected Bluetooth devices
• Filter Connected Devices: Display only devices currently connected
• Favourite Devices List: View devices marked as favorites (Note: returns empty list on macOS 12/Monterey and above)

4. Device Connection & Control

• Retrieve detailed information about a specific device
• Check device connection status
• Manually initiate connection requests
• Support precise operations using device ID or address

Technical Highlights

Dual-Mode Device Query

# Default: uses IOBluetooth framework API
blueutil --paired

# Alternative: uses system_profiler (recommended for multi-point devices)
BLUEUTIL_USE_SYSTEM_PROFILER=1 blueutil --paired

Multi-Device Connection Optimization: For Bluetooth devices capable of connecting to multiple devices simultaneously, blueutil provides a system_profiler mode to resolve issues where the IOBluetooth API fails to accurately report connection status for certain devices.

Flexible Query Parameters

• Customizable scan duration for device discovery
• Configurable number of recently used devices to display
• Option to list all historical devices or limit results

Advantages

🚀 Fast & Efficient

• No GUI required — operate directly from terminal
• Ideal for automation scripts and remote management
• Near-instant response with minimal latency

🔧 Automation-Friendly

• All operations can be integrated into scripts
• Suitable as a dependency for other applications
• Supports batch operations and device management

📊 Clear Status Output

• Clean, numeric status codes for easy interpretation
• Supports structured output formats like JSON
• Easily parsable by programs and scripts

🔄 Strong Compatibility

• Works across multiple macOS versions
• Adapted for newer system versions
• Provides fallback options to address compatibility issues

Use Cases

Development & Debugging

• Monitoring Bluetooth status during app development
• Bluetooth control in automated test scripts
• Real-time verification of device connection states

System Administration

• Remote Bluetooth management for servers
• Bulk device configuration and maintenance
• Power management optimization scripts

Daily Use

• Quickly toggle Bluetooth to save battery
• One-click connection to frequently used devices
• Instant device status checks

Notes

• API Limitation: Uses private IOBluetooth framework APIs — some functionalities may change with system updates
• System Compatibility: --favourites and --recent commands return empty lists on macOS 12/Monterey and above
• Experimental Feature: system_profiler mode is experimental and may not be compatible with all commands

Installation

Install via Homebrew:

brew install blueutil

Or compile from GitHub repository:

cd blueutil
make
sudo make install

blueutil, with its clean interface and robust functionality, has become an essential tool for macOS developers and administrators managing Bluetooth. It’s especially valuable for users who prefer command-line operations or need to automate Bluetooth workflows.