CheatPress

bluetoothctl Bluetooth from the shell

Version 5.87 · source

bluetoothctl, Postcard, light preview Light · Postcard 102 × 152 mm · PDF bluetoothctl, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF bluetoothctl, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
bluetoothctl, A5, light preview Light · A5 148 × 210 mm · PDF bluetoothctl, A5, dark preview Dark · A5 148 × 210 mm · PDF bluetoothctl, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
bluetoothctl, A4, light preview Light · A4 210 × 297 mm · PDF bluetoothctl, A4, dark preview Dark · A4 210 × 297 mm · PDF bluetoothctl, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
bluetoothctl, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF bluetoothctl, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF bluetoothctl, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
bluetoothctl, A3, light preview Light · A3 297 × 420 mm · PDF bluetoothctl, A3, dark preview Dark · A3 297 × 420 mm · PDF bluetoothctl, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
bluetoothctl, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF bluetoothctl, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF bluetoothctl, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
bluetoothctl, Letter, light preview Light · Letter 8.5 × 11 in · PDF bluetoothctl, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF bluetoothctl, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
bluetoothctl, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF bluetoothctl, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF bluetoothctl, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

bluetoothctl
Open the prompt
power on
Switch the adapter on
agent on
Handle pairing prompts
scan on
Look for devices
pair <dev>
Pair with a device
trust <dev>
Allow auto-reconnect
connect <dev>
Connect to it
devices
List known devices

Concepts

  1. Scan find it
  2. Pair exchange keys
  3. Trust allow reconnect
  4. Connect use profiles

Session

bluetoothctl
Open the interactive prompt
bluetoothctl <command>
Run one command and exit
Example: bluetoothctl devices Paired
bluetoothctl --timeout <seconds> scan on
Scan for a fixed time, then exit
bluetoothctl --agent <capability>
Start with an agent of that capability
bluetoothctl --monitor
Print low-level monitor output
bluetoothctl --version
Show the BlueZ version
help
List the commands of this menu
quit
Leave the prompt
menu <name>
Enter a submenu
back
Return to the main menu

Controller

power on
Switch the adapter on
Many setups need this after boot or an rfkill unblock.
power off
Switch the adapter off
show
Show controller state
list
List controllers
select <ctrl>
Pick the default controller
system-alias <name>
Set the name others see
discoverable on
Let other devices find this one
discoverable-timeout <seconds>
Show or set discoverable time
0 means no timeout.
pairable on
Accept incoming pairing requests
agent on
Register the pairing agent
default-agent
Make this agent the default
agent <capability>
Choose the agent's input/output type
DisplayOnly, DisplayYesNo, KeyboardDisplay, KeyboardOnly, NoInputNoOutput.
advertise on
Start LE advertising

Discover

scan on
Start scanning for devices
scan off
Stop scanning
scan le
Scan for Low Energy devices only
scan bredr
Scan for Classic devices only
devices
List known devices
devices Paired
List only paired devices
devices Connected
List only connected devices
devices Trusted
List only trusted devices
info <dev>
Show a device's state and profiles

Pair and connect

pair <dev>
Pair with a device
trust <dev>
Let it reconnect automatically
connect <dev>
Connect all profiles
disconnect <dev>
Drop the connection
remove <dev>
Forget the device and its pairing
Use it to fix a device that refuses to reconnect, then pair again.
connect <dev> <uuid>
Connect one profile only
Profile names such as a2dp-sink or hfp-hf also work.
untrust <dev>
Stop automatic reconnects
block <dev>
Refuse connections from it
unblock <dev>
Allow it again
bearer <dev> <last-seen/bredr/le>
Prefer Classic or LE for a dual-mode device
menu gatt
Browse and read GATT attributes (LE)
menu scan
Set scan filters (transport, RSSI, UUID)
menu advertise
Configure LE advertising data
menu player
Control media players on a connected device

Recipes

Pair a new headset
bluetoothctlpower onagent ondefault-agentscan on# wait for the device, then:pair AA:BB:CC:DD:EE:FFtrust AA:BB:CC:DD:EE:FFconnect AA:BB:CC:DD:EE:FFscan off
Reconnect a known device
bluetoothctl devices Pairedbluetoothctl connect AA:BB:CC:DD:EE:FFbluetoothctl info AA:BB:CC:DD:EE:FF
Start over with a stubborn device
bluetoothctl remove AA:BB:CC:DD:EE:FFbluetoothctl --timeout 15 scan on# then pair, trust, connect interactively
Script several commands
bluetoothctl <<EOFpower ondevices ConnectedshowEOF