Skip to content
Get packs

Guide · Agent skill

How to use the BluOS Player Control agent skill (blucli)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The blucli skill is an agent skill that teaches an AI agent to control Bluesound and NAD networked speakers through a command-line tool called blu. It is written for owners of those speakers who want to manage playback by typing plain requests, and for people who want machine-readable output for home audio scripts. After this guide you will know what the skill does, how to install it, how to trigger it, and what to watch for before letting an agent change your speakers.

BluOS Player Controlspinabot/brigade · MIT

Quick start

  1. 1Get the skill. Download the blucli ZIP from this page and unzip it.
  2. 2Place the folder. Copy the blucli folder into ~/.claude/skills/ or a project's .claude/skills/ directory, or upload it under Settings → Capabilities → Skills in the Claude apps.
  3. 3Install the blu tool. Install the command-line tool with Go using github.com/steipete/blucli/cmd/blu@latest.
  4. 4Find your players. Run blu devices to list the Bluesound or NAD players the tool can see.
  5. 5Make a request. Ask the agent in plain language, such as to set the volume or pause playback, and confirm the target speaker when asked.

What is an agent skill and what does blucli let the agent do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific task. This one covers BluOS players, the network audio platform used by Bluesound and NAD wireless speakers.

With the skill installed, the agent uses the blu command-line tool to find players on your network, check status, start, pause or stop playback, set volume, group speakers together, and search or play TuneIn radio stations.

  • Discover devices on your network
  • Start, pause and stop playback
  • Set volume
  • Group and ungroup speakers
  • Search and play TuneIn stations

How do you install the blucli skill?

Download the ZIP from this page and unzip it. Then place the blucli folder in one of these locations, depending on whether you want it for all projects or one project:

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Project only: .claude/skills/ inside your project folder

What do you need before the skill works?

The skill drives a command-line tool called blu, so that tool must be installed and available to the agent. The source suggests installing it with Go, which requires a Go toolchain on your machine. The install module is github.com/steipete/blucli/cmd/blu@latest.

You also need Bluesound or NAD players reachable on your local network. The skill only controls that hardware.

  • blu command-line tool (installed via Go: github.com/steipete/blucli/cmd/blu)
  • Go toolchain for the suggested install method
  • Bluesound or NAD players on the local network
go install github.com/steipete/blucli/cmd/blu@latest

How do you trigger the skill with natural requests?

Once installed, you ask the agent in plain language about your speakers, for example to pause the music, turn the volume to a set level, or play a radio station. The agent is expected to find the device, confirm it, and then run the matching blu command.

Behind the scenes the skill uses commands such as blu devices to list players, blu --device <id> status to check one, and blu volume set 15 to set volume. Targets can be chosen with --device accepting an ID, name or alias, the BLU_DEVICE environment variable, or a configured default.

  • Pause the living room speaker
  • Set the kitchen speaker volume to 15
  • Group the bedroom speaker with the patio speaker
  • Play jazz on TuneIn
blu devices blu --device <id> status blu play|pause|stop blu volume set 15

What are some practical examples?

The commands below are the ones listed in the skill's source. Grouping and TuneIn use the subcommands shown in the skill. Prefer --json when a script needs to parse the output.

Target selection follows this priority order: the --device flag first, then BLU_DEVICE, then the config default if one is set.

  • Grouping: blu group status, blu group add, blu group remove
  • TuneIn: blu tunein search "query" and blu tunein play "query"
  • For scripts: add --json to get machine-readable output
blu group status blu tunein search "query" blu tunein play "query"

What safety points should you know?

This skill runs scripts and uses the network. The agent acts on your local network, and the skill's instructions tell it to confirm the target device before changing playback. That confirmation is the main safeguard the skill describes; it does not add further checks.

Do not leave an agent to change volume on unattended speakers where a sudden loud change could harm someone, such as near sensitive hearing. Check the target name in every request before approving the action.

  • The skill runs scripts and uses your local network
  • The agent is told to confirm the target before changing playback
  • No additional checks beyond target confirmation are described in the source

What tips help you get reliable results?

Name your speakers clearly in the blu setup so the agent can match them to your requests. If you control several players, use --device with an ID, name or alias so the target is unambiguous. For scripts, ask for JSON output.

  • Use clear, distinct speaker names or aliases
  • Set BLU_DEVICE if you usually control one player
  • Use --json for scripts

What people use it for

  • Pausing or stopping music in one room from a chat request
  • Setting volume on a named speaker to a specific level
  • Grouping speakers so one request plays across several rooms
  • Starting a TuneIn radio station by search term
  • Scripting home audio routines that read blu output in JSON

Frequently asked questions

How do I install the blucli skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills. You also need the blu tool installed.

What do I need to use blucli?

You need the blu command-line tool, a Go toolchain if you use the suggested Go install, and Bluesound or NAD players reachable on your local network. Without those players the skill has no benefit.

Is the blucli skill free?

The skill is published under the MIT licence, as stated in its listing. The source does not describe pricing for the blu tool or any other cost.

Does blucli work with NAD speakers as well as Bluesound?

Yes. The skill description says it controls Bluesound and NAD players, so NAD networked speakers are covered alongside Bluesound.

Why won't the agent find my speaker?

The skill relies on blu discovering players on your local network. Check that the speakers are powered on and reachable from your computer, then run blu devices to see what the tool can find. The source does not list other troubleshooting steps.

Is it safe to let an AI agent change my speaker volume?

The skill tells the agent to confirm the target device before changing playback, but it adds no further safeguards. Avoid unattended use where a sudden volume change could harm someone, and check the speaker name before approving changes.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose blucli if you own Bluesound or NAD networked speakers and want to control them by typing requests to an agent or by scripting with JSON output. Skip it if you have no BluOS hardware, or if you plan to let an agent change volume unattended near anyone with sensitive hearing, since its only check is confirming the target.

Download the skill