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.


    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:

    Power: 1
    Discoverable: 0
    blueutil - Example

    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
    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 OptionsDescription
    --format FORMATChange 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 CodesDescription
    1General failure.
    64Wrong usage, such as missing or unexpected arguments.
    69Bluetooth or interface not available.
    70Internal error.
    71System error, like a shortage of memory.
    75Timeout error.


blueutil is a powerful tool that allows you to manage Bluetooth on your macOS system efficiently. Whether you need to control Bluetooth power, discover devices, manage connections, or explore device information, blueutil simplifies the process, all from the comfort of your terminal.

To explore more about blueutil and its capabilities, refer to the official GitHub repository:

Facing issues? Have Questions? Post them here! I am happy to answer!

Author Info:

Rakesh (He/Him) has over 14+ years of experience in Web and Application development. He is the author of insightful How-To articles for Code2care.

Follow him on: X

You can also reach out to him via e-mail:

Copyright © Code2care 2024 | Privacy Policy | About Us | Contact Us | Sitemap