bluetoothctl: CLI Bluetooth Device Manager

bluetoothctl: CLI Bluetooth Device Manager

A pragmatic, example-first guide to controlling Bluetooth from the terminal using bluetoothctl. Great for headless servers, scripting, or quick setups.

Quick start: enter the bluetoothctl shell

  • Start the interactive shell:
bluetoothctl

Once inside, you can type commands directly. To exit, type quit or press Ctrl-D.

Tip: Running bluetoothctl with sudo is rarely necessary for modern BlueZ setups, but some systems require elevated privileges for certain actions.

Basic workflow (typical sequence)

A common flow is: power on the controller, scan for devices, pair, and connect. You can perform these steps inside the bluetoothctl shell.

1) Power the controller on

bluetoothctl power on

If the controller is off by default, this enables it. Some adapters may ignore the command if they have been disabled by hardware switch.

2) Make devices discoverable / scan for devices

bluetoothctl scanning on
  • This shows nearby devices as they are discovered.
  • When done, stop scanning to save CPU and battery:
bluetoothctl scanning off

Tip: Scanning can produce many results; use devices to list known devices and filter by MAC.

3) List known devices

bluetoothctl devices

This prints lines like:

Device XX:XX:XX:XX:XX:XX Device_Name

4) Pair a device

bluetoothctl pair XX:XX:XX:XX:XX:XX
  • Pairing may require you to confirm a passkey or enter a PIN depending on the device.
  • Some devices require you to put them in pairing mode before attempting to pair.

5) Trust and connect

Sometimes you want the device to reconnect automatically after a reboot:

bluetoothctl trust XX:XX:XX:XX:XX:XX

Then connect:

bluetoothctl connect XX:XX:XX:XX:XX:XX

6) Disconnect or remove

bluetoothctl disconnect XX:XX:XX:XX:XX:XX

To remove a device from the pairings:

bluetoothctl remove XX:XX:XX:XX:XX:XX

7) Help

If you’re unsure about available commands:

bluetoothctl help

Practical examples

  • Example: Pair and connect to a device
bluetoothctl
power on
scan on
# wait a moment to discover the device, then:
pair 12:34:56:78:9A:BC
trust 12:34:56:78:9A:BC
connect 12:34:56:78:9A:BC
  • Example: List devices and try to connect without re-pairing
bluetoothctl
devices
connect 12:34:56:78:9A:BC

Common pitfalls and how to avoid them

  • Pitfall: Controller is off or blocked by hardware switch
    • Check power state is on and your adapter is not blocked:
      • bluetoothctl power on
      • rfkill list (look for Bluetooth and ensure it’s unblocked)
  • Pitfall: Not powering the controller before scanning
    • Always turn the controller on first; scanning may fail otherwise.
  • Pitfall: Pairing prompts require user interaction on the device
    • Some devices show a PIN or require confirmation on the device; ensure both sides are ready.
  • Pitfall: The agent is not running for pairing in some environments
    • Inside bluetoothctl, you may need to set an agent:
      • agent on
      • default-agent
  • Pitfall: Reboots lose pairing information if not saved or if the adapter forgets devices
    • Use trust to keep connections persistent where appropriate.

Tips for smoother sessions

  • Use a serial-like workflow in scripts:
    • bluetoothctl << EOF power on scan off devices pair XX:XX:XX:XX:XX:XX trust XX:XX:XX:XX:XX:XX connect XX:XX:XX:XX:XX:XX EOF
  • If a device refuses to pair, remove and re-scan:
    • remove XX:XX:XX:XX:XX:XX
    • scan on
  • Check BlueZ version differences
    • Newer BlueZ versions sometimes require agent on and default-agent for certain automation tasks.

Quick reference (inside bluetoothctl)

  • Enter shell: bluetoothctl
  • List devices: devices
  • Power on/off: power on|off
  • Scan: scan on|off
  • Pair: pair
  • Trust: trust
  • Connect: connect
  • Disconnect: disconnect
  • Remove: remove
  • Help: help

Final note

bluetoothctl is a powerful, low-friction way to manage Bluetooth on Linux systems, especially on headless servers or scripts. Start small, verify each step, and progressively automate routine device management with careful checks for success responses.

See Also