bluetooth-wizard

bluetooth-wizard [--device=BDADDR] [--agent] [--quit]

--device=BDADDR
    Launch wizard to pair with specific Bluetooth device address (e.g., AA:BB:CC:DD:EE:FF)

--agent
    Register as pairing agent to handle passkeys and authorization requests

--quit
    Quit any running wizard instance

The bluetooth-wizard is a GTK-based graphical utility from the GNOME Bluetooth project, designed to simplify the process of discovering, pairing, and connecting Bluetooth devices on Linux systems using the BlueZ stack.

It launches a user-friendly wizard interface that guides users through Bluetooth setup, making it accessible for non-technical users. Unlike command-line tools like bluetoothctl, it provides visual feedback, device lists, PIN entry dialogs, and progress indicators.

Primarily used in GNOME environments (e.g., Ubuntu, Fedora), it integrates with the desktop's Bluetooth applet. Invoke it from terminal to pair a specific device or troubleshoot connections. It handles agent registration for passkey/pairing requests and supports HID, audio, and other profiles.

Requires a running Bluetooth service (bluetoothd) and D-Bus. Works on X11 and Wayland. Ideal for quick pairings without deep CLI knowledge.

Graphical tool; requires display server (X11/Wayland) and gnome-bluetooth package. May not work headless. Dependent on BlueZ daemon running.

Pair specific device: bluetooth-wizard --device=00:11:22:33:44:55
Run agent: bluetooth-wizard --agent

Installed via gnome-bluetooth or bluez-gnome (e.g., apt install gnome-bluetooth on Debian/Ubuntu)

Introduced in gnome-bluetooth ~2.28 (2010) as part of BlueZ integration for GNOME 3. Evolved with Wayland support in later versions (3.x+). Maintained by GNOME project; usage peaked in Unity/GNOME shells pre-2015.

bluetoothctl(1), bluetoothd(8), hciconfig(8), rfkill(8)