Back to Commands

bluetoothctl

networkingLinux
The bluetoothctl command is one of the most frequently used commands in Linux/Unix-like operating systems. bluetoothctl The bluetoothctl command is an interactive command-line tool for controlling and managing Bluetooth devices on Linux systems. It provides a comprehensive set of functions for scanning, pairing, connecting, and configuring Bluetooth devices from the terminal.
See ExamplesView Syntax

Quick Reference

Command Name:

bluetoothctl

Category:

networking

Platform:

Linux

Basic Usage:

bluetoothctl scan on

Common Use Cases

  • 1

    Device pairing

    Pair Bluetooth devices with your Linux system

  • 2

    Connection management

    Connect, disconnect, and manage paired Bluetooth devices

  • 3

    Device discovery

    Scan for and identify available Bluetooth devices in range

  • 4

    System configuration

    Configure Bluetooth adapter settings like discoverability and name

Syntax

bluetoothctl [command]

Options

Command Description
help Display help for available commands
show Show controller information
list List available controllers
select [addr] Select a specific controller by address
devices List available devices
paired-devices List paired devices
power [on/off] Toggle power on the adapter
discoverable [on/off] Toggle discoverable mode
pairable [on/off] Toggle pairable mode
scan [on/off] Scan for devices
pair [MAC] Pair with device
trust [MAC] Trust device
untrust [MAC] Untrust device
block [MAC] Block device
unblock [MAC] Unblock device
connect [MAC] Connect to device
disconnect [MAC] Disconnect from device
info [MAC] Get device information
system-alias [name] Set the device name
remove [MAC] Remove device
quit Exit interactive mode

Examples

How to Use These Examples

The examples below show common ways to use the bluetoothctl command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

#

Basic Examples:

# Start the interactive bluetoothctl shell
bluetoothctl
# Show information about the controller bluetoothctl show
# List available Bluetooth devices bluetoothctl devices
# Turn Bluetooth adapter on bluetoothctl power on
# Make your device discoverable bluetoothctl discoverable on
# Scan for nearby Bluetooth devices bluetoothctl scan on

Advanced Examples:

# Pair with a specific device by MAC address
bluetoothctl pair 00:11:22:33:44:55

# Connect to a paired device
bluetoothctl connect 00:11:22:33:44:55

# Trust a paired device
bluetoothctl trust 00:11:22:33:44:55

# Remove a paired device
bluetoothctl remove 00:11:22:33:44:55

# Run a specific command without entering the interactive shell
bluetoothctl -- power on

# Run multiple commands in sequence
bluetoothctl -- power on discoverable on pairable on scan on

# Set the device name for your Bluetooth adapter
bluetoothctl -- system-alias "My Linux Device"

# Get information about a specific device
bluetoothctl -- info 00:11:22:33:44:55

Try It Yourself

Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

Understanding Syntax

Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

Notes

Important Notes:

The bluetoothctl command provides an interactive interface for managing Bluetooth devices on Linux systems using the BlueZ stack.

Interactive Mode:

  • When run without arguments, bluetoothctl enters an interactive shell with a [bluetooth]# prompt.
  • Commands can be entered one at a time in this interactive shell.
  • Use help to see all available commands.
  • Use quit or press Ctrl+D to exit the interactive shell.

Non-Interactive Mode:

  • Use bluetoothctl -- command1 command2 ... to run commands without entering the interactive shell.
  • This is useful for scripting and automation.

Common Workflow:

  1. Power on the adapter: power on
  2. Make the adapter discoverable: discoverable on
  3. Scan for devices: scan on
  4. Pair with a device: pair MAC_ADDRESS
  5. Trust the device: trust MAC_ADDRESS
  6. Connect to the device: connect MAC_ADDRESS

Troubleshooting Tips:

  • If a device won't pair, try removing it first with remove MAC_ADDRESS and then pair again.
  • Some devices require a PIN code for pairing. The PIN will be requested during the pairing process.
  • If you're having issues with a device not connecting, ensure it's trusted with trust MAC_ADDRESS.
  • Use info MAC_ADDRESS to get detailed information about a device's capabilities and connection status.

System Requirements:

  • Requires the BlueZ package to be installed (usually included in most Linux distributions).
  • Your system must have a Bluetooth adapter (built-in or USB dongle).
  • You may need root privileges to perform certain operations like scanning or changing adapter settings.

Tips & Tricks

1

Use the power on command to enable Bluetooth

2

Use the power off command to disable Bluetooth

3

Use the scan on command to start scanning for devices

4

Use the scan off command to stop scanning for devices

5

Use the pairable on command to make the device pairable

Common Use Cases

Device pairing

Pair Bluetooth devices with your Linux system

Connection management

Connect, disconnect, and manage paired Bluetooth devices

Device discovery

Scan for and identify available Bluetooth devices in range

System configuration

Configure Bluetooth adapter settings like discoverability and name

Automation

Script Bluetooth operations for automated tasks and device management

Related Commands

These commands are frequently used alongside bluetoothctl or serve similar purposes:

Explore All Commands

Use Cases

1

Device pairing

Pair Bluetooth devices with your Linux system

2

Connection management

Connect, disconnect, and manage paired Bluetooth devices

3

Device discovery

Scan for and identify available Bluetooth devices in range

4

System configuration

Configure Bluetooth adapter settings like discoverability and name

5

Automation

Script Bluetooth operations for automated tasks and device management

Learn By Doing

The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the bluetoothctl command works in different scenarios.

See ExamplesTry Lab Exercises
$ bluetoothctl
View All Commands