bluetoothctl

Control Bluetooth devices from the command line

TLDR

Enter interactive shell

$ bluetoothctl

List devices

$ bluetoothctl devices

Power controller on/off

$ bluetoothctl power on

Pair with device

$ bluetoothctl pair AA:BB:CC:DD:EE:FF

Connect to device

$ bluetoothctl connect AA:BB:CC:DD:EE:FF

Disconnect device

$ bluetoothctl disconnect AA:BB:CC:DD:EE:FF

Remove device

$ bluetoothctl remove AA:BB:CC:DD:EE:FF

SYNOPSIS

bluetoothctl [OPTIONS] [COMMAND]

DESCRIPTION

bluetoothctl manages Bluetooth devices on Linux. It provides an interactive shell for discovering, pairing, connecting, and managing Bluetooth devices.

PARAMETERS

-a, --agent capability

Register an agent handler with the specified capability.

-e, --endpoints

Register media endpoints.

-m, --monitor

Enable monitor output.

-t, --timeout seconds

Timeout for non-interactive mode.

-v, --version

Display version.

-h, --help

Display help.

list

List available controllers

show [ctrl]

Show controller information

select ctrl

Set the default controller

devices [filter]

List known devices (filter: Paired, Bonded, Trusted, Connected)

power on|off

Turn Bluetooth controller on or off

scan on|off

Start or stop device discovery

pair address

Pair with device by MAC address

connect address

Connect to paired device

disconnect address

Disconnect from device

remove address

Remove device from known list

trust address

Mark device as trusted

untrust address

Remove trust from device

info address

Show device information

block address

Block a device from connecting

unblock address

Unblock a previously blocked device

discoverable on|off

Set controller discoverability

agent on|off|capability

Register or unregister agent

help

Show available commands

CAVEATS

Requires the bluetooth service to be running. Some operations require devices to be in pairing mode. MAC addresses are in format AA:BB:CC:DD:EE:FF.

HISTORY

bluetoothctl is part of BlueZ, the official Linux Bluetooth protocol stack.