DOCSEARCHbyAlgolia
Submit Docs

blueutil

repository·main·Indexed 23 days ago

https://github.com/toy/blueutil

A command-line interface for managing Bluetooth on macOS. blueutil allows users to control power, discoverability, pair/unpair devices, and query device information. It supports various output formats including JSON and can be installed via Homebrew, MacPorts, or from source.

Tokens
858
Snippets
2
Records
7
Agent score
29%

What's inside blueutil

  1. Use the system_profiler alternative for device queries

    main

    By default, blueutil uses the IOBluetooth framework. To resolve issues where multi-point devices do not report connection status correctly, you can use the system_profiler method by setting the BLUEUTIL_USE_SYSTEM_PROFILER=1 environment variable.

    Warning: This method is experimental and may have compatibility issues with some commands.

    BLUEUTIL_USE_SYSTEM_PROFILER=1 blueutil --paired

  2. Install blueutil via Homebrew, MacPorts, or Source

    main

    You can install blueutil using several package managers or by building from source.

    Homebrew

    brew install blueutil

    To update:

    brew update && brew upgrade blueutil

    To uninstall:

    brew remove blueutil

    MacPorts

    Note: You will likely need to prefix these commands with sudo.

    port install blueutil

    To update:

    port selfupdate && port upgrade blueutil

    To uninstall:

    port uninstall blueutil

    From Source

    git clone https://github.com/toy/blueutil.git
cd blueutil
make
# install/update
make install
# uninstall
make uninstall

    Note: make install and make uninstall may require sudo.

    brew install blueutil

  4. blueutil exit codes

    main

    When using blueutil in scripts, check the exit code to determine the result:

    CodeMeaning
    0Success
    1General failure
    64Wrong usage (missing/unexpected arguments/parameters)
    69Bluetooth or interface not available
    70Internal error
    71System error (e.g., shortage of memory)
    75Timeout error
    134Abort signal (may indicate absence of access to Bluetooth API)

  5. Change blueutil output format

    main

    Use the --format FORMAT flag to change the output of --info and all listing commands.

    Available formats:

    • default: Human readable text (not for scripts).
    • new-default: Human readable comma-separated key-value pairs (EXPERIMENTAL).
    • json: Compact JSON.
    • json-pretty: Pretty-printed JSON.

  6. Use blueutil CLI to manage Bluetooth power and discoverability

    main

    Use the following flags to query or modify the Bluetooth power and discoverability state.

    • -p, --power [STATE]: Output power state (1 or 0) or set it.
    • -d, --discoverable [STATE]: Output discoverable state (1 or 0) or set it.

    STATE can be: 1, on, 0, off, or toggle.

  7. List and manage Bluetooth devices

    main

    Use these flags to list different categories of devices:

    • --paired: List paired devices.
    • --connected: List connected devices.
    • --recent [N]: List recently used devices (default 10, use 0 for all). Note: returns empty list on macOS 12+.
    • --favourites, --favorites: List favourite devices. Note: returns empty list on macOS 12+.
    • --inquiry [T]: Inquire devices in range for a duration of T seconds (default 10s).

    To perform actions on a specific device, use its ID (address in formats xxxxxxxxxxxx, xx-xx-xx-xx-xx-xx, or xx:xx:xx:xx:xx:xx, or the device name):

    • --info ID: Show information about a device.
    • --is-connected ID: Check if a device is connected (1 or 0).
    • --connect ID: Create a connection to a device.
    • --disconnect ID: Close the connection to a device.
    • --pair ID [PIN]: Pair with a device (optional PIN up to 16 chars).
    • --unpair ID: (EXPERIMENTAL) Unpair a device.
    • --add-favourite ID: (macOS 12+ does nothing) Add to favourites.
    • --remove-favourite ID: (macOS 12+ does nothing) Remove from favourites.