hcitool

Configure and manage Bluetooth connections

TLDR

Scan for Bluetooth devices

$ hcitool scan

Output the name of a device, returning its MAC address

$ hcitool name [bdaddr]

Fetch information about a remote Bluetooth device

$ hcitool info [bdaddr]

Check the link quality to a Bluetooth device

$ hcitool lq [bdaddr]

Modify the transmit power level

$ hcitool tpl [bdaddr] [0|1]

Display the link policy

$ hcitool lp

Request authentication with a specific device

$ hcitool auth [bdaddr]

Display local devices

$ hcitool dev

SYNOPSIS

hcitool [-i ] [COMMAND [args...]]

PARAMETERS

-i, --dev hciX
    Select local Bluetooth HCI device (default hci0)

--help
    Print usage summary and exit

--version
    Print version information and exit

hcitool is a command-line tool from the BlueZ Linux Bluetooth stack for interacting with Bluetooth controllers via the Host Controller Interface (HCI). It enables scanning for nearby devices, retrieving detailed information about local or remote Bluetooth devices, managing connections, authentication, encryption, link keys, and sending raw HCI commands for low-level control.

Common use cases include discovering devices with hcitool scan, getting device features or RSSI, and debugging connectivity issues. It supports multiple HCI devices and is script-friendly.

Note: hcitool is deprecated since BlueZ 5.50 (2017). Modern alternatives like bluetoothctl (interactive) and btmgmt (management) are recommended for better security, D-Bus integration, and LE support. Still available in many distributions but expect eventual removal.

CAVEATS

Requires root privileges for most operations (use sudo). Deprecated in BlueZ 5.50+; lacks Bluetooth Low Energy (LE) support in older versions. Use bluetoothctl or btmgmt instead. May not work with modern kernel HCI features.

COMMON SUBCOMMANDS

scan [types] [length] [numrsp] – Discover devices
info – Remote device info
devinfo – Local device info
con – Connect device
cmd [params] – Raw HCI command

HISTORY

Developed as part of BlueZ (Linux Bluetooth) since ~2001 by Marcel Holtmann and others. Primary HCI tool through BlueZ 5.49. Deprecated in 5.50 (2017) with shift to D-Bus tools; marked legacy in 5.64 (2020). Widely used for scripting/debugging until interactive alternatives matured.