blew -- BLE scanner and CLI tool for Mac OS X

Stop fumbling with GUI apps to debug Bluetooth Low Energy devices. blew gives you full BLE control from the macOS command line: scan the airwaves, drill into any device's GATT tree, read and write characteristics, stream live notifications, and even spin up a virtual peripheral that other devices can connect to.

Why blew

- One tool, zero ceremony. Scan, connect, inspect, read, write, subscribe -- each is a single command. Auto-connect means you never have to manually pair before doing real work.
- Interactive when you want it. Launch the REPL for an exploratory session with tab completion, persistent history, and background subscriptions that print while you keep typing.
- Scriptable when you need it. Chain commands with exec, pipe machine-readable kv output into awk or a log file, and use deterministic exit codes in CI or monitoring scripts.
- Full GATT visibility. Print the service/characteristic tree of any device in one shot. Read all values inline. Look up any Bluetooth SIG characteristic's field-level spec without even connecting.
- Peripheral mode. Turn your Mac into a virtual BLE device. Define a GATT server from a JSON config, or clone a real device's entire service tree and replay it.
- Human-readable by default. Standard Bluetooth SIG UUIDs are resolved to their names everywhere -- scan results, GATT trees, notifications -- sourced from the official Bluetooth SIG database.

Modes of operation

- Command mode -- run a single command, then exit: blew [global-options] <command> [command-options]
- Interactive REPL -- run blew with no command for a readline-style shell with history and tab completion
- Script mode -- run a semicolon-separated sequence sharing one connection: blew exec "connect -n Sensor; gatt tree; read -f uint8 2A19"
- MCP server mode -- expose all BLE operations as MCP tools for AI agents: blew mcp

> Requires macOS 13+ and Bluetooth permission.

Things you can do

Clone a real device and impersonate it. Walk up to a heart rate monitor, clone its full GATT tree, and your Mac starts advertising as that device. Other apps can connect to the clone as if it were the real thing:

% blew periph clone -n "Heart Rate Monitor" --save hr.json

Watch the BLE airwaves live. See every device around you with signal-strength bars, updating in real time. Filter by name, service, or signal floor to zero in on what you need in a crowded venue:

% blew scan -w -R -70

X-ray a device in one shot. Connect, discover all services, read every readable characteristic, and print the whole thing as a tree, including names, properties, descriptors and live values:

% blew -n "Thingy" gatt tree -dr

Look up any Bluetooth SIG characteristic without a device. Instantly see the field-level structure of any standard characteristic, like byte layout, types, conditional fields:

% blew gatt info 2A37    # Heart Rate Measurement spec

Stream sensor data straight to a log. Subscribe to a characteristic, format values as key-value pairs, and pipe to a file or another tool. Runs headless, exits cleanly on timeout:

% blew -o kv sub -n "Sensor" -f uint16le -d 3600 fff1 >> hourly.log

Spin up a virtual BLE device from a JSON file. Define services, characteristics, properties, and initial values in a config file and start advertising in one command:

% blew periph adv --config health-thermometer.json

Run a multi-step test sequence as a one-liner. Connect, inspect, read, write, wait, read again or subscribe to notifications as a single command:

% blew exec -k "connect -n Sensor; gatt tree; write -f uint8 fff2 01; sleep 2; read -f uint16le fff1"

---

Installation

Homebrew

brew install stass/tap/blew

Requirements

- macOS 14 (Sonoma) or later
- Xcode 16 or later (Swift 6.0+ toolchain)

The MCP server (the blew mcp subcommand) depends on the MCP swift-sdk, which requires the Swift 6.1 toolchain (Xcode 16.3+). To keep blew building on older toolchains, MCP support is compiled in conditionally: when built with Swift 6.1 or newer the mcp subcommand is available; when built with Swift 6.0.x (Xcode 16.0–16.2) the MCP server is omitted and every other command works unchanged. No flags are needed — the detection happens automatically in Package.swift.

Build from source

git clone --recurse-submodules https://github.com/stass/blew.git
swift build -c release
cp .build/release/blew /usr/local/bin/blew

--recurse-submodules is required — the Bluetooth SIG name and characteristic databases are included as git submodules under Vendor/. The Swift build generates all data files automatically from the submodule data.

On first run, macOS will prompt for Bluetooth permission. Grant it in System Settings → Privacy & Security → Bluetooth.

---

Quick start

```sh