Working with Bluetooth on Mac Terminal using blueutil Commands

Bluetooth is the most popular wireless technology which has become an integral part of our daily lives. Whether you're connecting wireless AirPods or headphones, keyboards, or mice, or to share files from other devices using AirDrop, or even controlling devices, Bluetooth plays a key role in today's computing.

If you have a macOS device and looking to take control of your Bluetooth settings from the command line or Python or Shell Script, blueutil is the tool you can make use of. In this article, we explore how to make use of blueutil to manage Bluetooth on your Mac.

What is blueutil?

blueutil is a command-line utility designed specifically for macOS that empowers us to control various Bluetooth using the terminal. We can turn Bluetooth on or off, list paired devices, inquire about nearby devices, or even connect and disconnect.

Installation

Before diving into the commands, you'll need to install blueutil. If you haven't already, you can do so using Homebrew, the popular package manager for macOS. Open your terminal and run the following command.

brew install blueutil

You should have HomeBrew installed on your Mac to run the above command - Install Brew on Mac (M1/M2/Intel)

Basic Usage:

Let's start with the basics. Running blueutil without any options will output the current state of your Bluetooth:

blueutil

Power: 1
Discoverable: 0



You'll see information about the power state and discoverable state of your Bluetooth.

Turning Bluetooth On and Off

You can turn Bluetooth on or off using blueutil with the -p or --power option, followed by the desired state (1 for on, 0 for off):

Example: Turn Bluetooth on

blueutil --power 1

Example: Turn Bluetooth off

blueutil --power 0

Checking Discoverable State

The discoverable state of your Bluetooth can also be checked and set using blueutil:

Example: Check discoverable state

blueutil --discoverable

BS|Example: Set discoverable state (1 for discoverable, 0 for non-discoverable)

blueutil --discoverable 1

Exploring Devices

blueutil provides several commands to explore and interact with Bluetooth devices.

Listing Paired Devices

blueutil --paired

Inquiring Nearby Devices

To discover nearby devices, you can use the --inquiry option. By default, it will scan for devices for 10 seconds:

blueutil --inquiry

Listing Connected Devices

To list the devices currently connected to your Mac, use the following command:

blueutil --connected

Managing Individual Devices

blueutil --info <device_id>

Connecting and Disconnecting

To create a connection with a device, use the --connect option followed by the device's ID:

blueutil --connect <device_id>

Conversely, you can close a connection to a device using the --disconnect option:

blueutil --disconnect <device_id>

Pairing and Unpairing

Pairing with a device is straightforward. Use the --pair option, followed by the device's ID. If required, you can also provide a PIN of up to 16 characters:

blueutil --pair <device_id> [PIN]

To unpair a device, you can use the --unpair option:

blueutil --unpair <device_id>

Adding and Removing from Favorites

blueutil --add-favourite <device_id>

Conversely, you can remove a device from your favorites list using the --remove-favourite option:

blueutil --remove-favourite <device_id>

Advanced Options

Advanced Options	Description
--format FORMAT	Change output format for device information and listing commands.
--wait-connect ID [TIMEOUT]	Wait for a device to connect (EXPERIMENTAL).
--wait-disconnect ID [TIMEOUT]	Wait for a device to disconnect (EXPERIMENTAL).
--wait-rssi ID OP VALUE [PERIOD [TIMEOUT]]	Wait for a device's RSSI (Received Signal Strength Indicator) value (EXPERIMENTAL).




Waiting for Events

blueutil provides experimental options to wait for specific events related to devices:

--wait-connect: Wait for a device to connect.
--wait-disconnect: Wait for a device to disconnect.
--wait-rssi: Wait for a device's RSSI (Received Signal Strength Indicator) value.

Exit Codes

blueutil returns exit codes that can help you understand the result of your command:

Exit Codes	Description
0	Success.
1	General failure.
64	Wrong usage, such as missing or unexpected arguments.
69	Bluetooth or interface not available.
70	Internal error.
71	System error, like a shortage of memory.
75	Timeout error.