# Bluez

> Auth/lab ref: BlueZ Bluetooth stack and CLI workflow: Linux, covering bluetoothctl-driven discovery, pairing, BLE inspection, and low-level troubleshooting utilities.

- Skill: `aeondave/bluez` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aeondave/bluez`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aeondave/bluez/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: GPL-2.0 / LGPL-2.1
- Author: AeonDave (https://skillmd.com/u/aeondave)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aeondave/bluez

---


# BlueZ

Linux Bluetooth stack and operator toolkit for Bluetooth Classic and BLE discovery, connection, and debugging.

## Why BlueZ

Use BlueZ as the baseline Bluetooth skill when you need:
- adapter bring-up and health checks
- BLE or Classic discovery from Linux
- pairing / trust / connection workflows
- Bluetooth service and characteristic inspection
- low-level monitoring and debugging

## Quick Start

```bash
# verify controller state
bluetoothctl list
bluetoothctl show

# interactive discovery
bluetoothctl
[bluetooth]# power on
[bluetooth]# agent on
[bluetooth]# default-agent
[bluetooth]# scan on
```

## Core Workflows

### Live device discovery

```bash
bluetoothctl scan on
```

### Pair and trust a device

```bash
bluetoothctl
[bluetooth]# pair AA:BB:CC:DD:EE:FF
[bluetooth]# trust AA:BB:CC:DD:EE:FF
[bluetooth]# connect AA:BB:CC:DD:EE:FF
```

### Low-level monitor / troubleshooting

```bash
btmon
```

Use `btmon` when pairing, advertising visibility, or GATT behavior is unclear.

## Practical Scope

BlueZ is the foundation. Prefer it before niche scanners because:
- it is current and maintained upstream
- it ships the real Linux Bluetooth stack
- it exposes both high-level and low-level workflows

## Notes on Older Utilities

Older tooling such as `gatttool` or some deprecated tools may still appear in guides, but modern workflows should prefer current BlueZ client tooling where possible.

## Relationship to Other Wireless Skills

| Skill | Best use |
|---|---|
| `bluez` | Core Linux Bluetooth discovery, pairing, monitoring |
| `kismet` | Passive multi-RF visibility including Bluetooth with supported hardware |
| `sparrow-wifi` | GUI/agent Bluetooth awareness plus Wi‑Fi/HackRF/Ubertooth workflows |

## Resources

| File | When to load |
|---|---|
| `references/scan-read-debug-workflow.md` | For bluetoothctl, BLE scanning, service inspection, and monitor-first debugging workflows |