blucli is a command-line client for discovering and controlling Bluesound and NAD players that run BluOS. It gives people and scripts access to playback, grouping, queues, presets, browsing, and diagnostics over the local network.

Homebrew installs the blu command on macOS or Linux:

brew install steipete/tap/blucli

With Go 1.25 or newer:

go install github.com/steipete/blucli/cmd/blu@latest

Prebuilt macOS, Linux, and Windows archives are available from GitHub Releases. For a container-based setup, see the Docker guide.

Discover players, then address one by its discovery name or host:port:

blu devices
blu --device "Living Room" status
blu --device 192.168.1.19:11000 now

When discovery finds exactly one player, blu status selects it automatically. Otherwise, pass --device, set BLU_DEVICE, or configure a default.

See the usage guide for command examples, Spotify setup, Docker, shell completions, and automation notes. The protocol and implementation spec documents discovery, BluOS endpoints, CLI behavior, and the project layout.

blu resolves a target in this order:

1. --device <host:port|name|alias>
2. BLU_DEVICE
3. default_device in the config file
4. the discovery cache, when it contains exactly one player
5. live discovery, when it finds exactly one player

Run blu devices to refresh the cache. Discovery names work directly; aliases are useful for custom shortcuts or disambiguation.

The default config file is ~/Library/Application Support/blu/config.json on macOS and ~/.config/blu/config.json on Linux. Override it with --config <path>.

{
  "default_device": "192.168.1.19:11000",
  "aliases": {
    "kitchen": "192.168.1.19:11000",
    "office": "192.168.1.115:11000"
  }
}

go build -o dist/blu ./cmd/blu
go test ./...
golangci-lint run --timeout=5m

The repository also provides equivalent pnpm build, pnpm test, and pnpm lint helpers.

MIT