Guide · Agent skill
How to use the Sonos Speaker Control agent skill (sonoscli)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The sonoscli skill teaches an AI agent to run the sonos command-line tool, which controls Sonos speakers on your local network. It is aimed at people who own Sonos hardware and want to manage playback by asking in plain language, as well as developers who already use the sonos CLI. After following this guide you will be able to install the skill, trigger it with everyday requests, and fix the most common discovery errors.
Sonos Speaker Controlspinabot/brigade · MIT Download the skill Quick start
- 1Install the Go toolchain. The sonos tool is installed through Go, so make sure a Go toolchain is available on your machine.
- 2Install the sonos tool. Run go install github.com/steipete/sonoscli/cmd/sonos@latest to install the command-line tool the skill depends on.
- 3Download and place the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
- 4Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the ZIP instead.
- 5Check discovery. Run sonos discover in a terminal to confirm your speakers are found on the local network.
- 6Ask in plain language. Request actions such as pausing a room or setting volume, naming the speaker in your request.
What the sonoscli skill lets your agent do
An agent skill is a folder containing a SKILL.md file with instructions the agent reads when a task matches. This skill's instructions tell the agent to use the sonos tool to talk to Sonos speakers on your local network.
Once installed, the agent can find your speakers, check what is playing, play, pause or stop playback, set volume, and group rooms. The skill also covers grouping, favorites, the queue, and optional Spotify search through Sonos.
- Discover speakers on the network
- Check status of a room
- Play, pause or stop playback
- Set volume for a named speaker
- Group, ungroup or solo rooms
- Open favorites and manage the queue
- Search Spotify through Sonos (optional)
Install the sonos tool and the skill
The skill needs the sonos command-line tool. The source lists its install method as Go, using the module github.com/steipete/sonoscli/cmd/sonos@latest, so you need a Go toolchain for this step. Confirm the tool works by running sonos discover in a terminal.
To install the skill itself, download the ZIP from the page you found this on and choose one of these options:
- Claude Code, personal: unzip the download into ~/.claude/skills/
- Claude Code, per project: unzip the download into your project's .claude/skills/ folder
- Claude apps: go to Settings → Capabilities → Skills and upload the ZIP
go install github.com/steipete/sonoscli/cmd/sonos@latestTrigger the skill with natural requests
You do not need to type commands. Describe what you want in plain language, and the agent will pick the skill when the request matches its description of controlling Sonos speakers. Naming the room helps, because the tool targets speakers by name.
Behind the scenes the agent runs commands such as sonos status --name "Kitchen" or sonos volume set 15 --name "Kitchen".
- "Find my Sonos speakers."
- "What is playing in the kitchen?"
- "Pause the living room."
- "Set the bedroom volume to 15."
- "Group the kitchen with the patio."
- "Play my favorites in the office."
sonos discover
sonos status --name "Kitchen"
sonos play|pause|stop --name "Kitchen"
sonos volume set 15 --name "Kitchen"Commands the skill uses for grouping, favorites, queue and Spotify
The skill's quick reference lists grouping, favorites, queue and Spotify search commands. Use these as the vocabulary for what the agent can run. Spotify search is optional and needs extra credentials, covered in the requirements section below.
- Grouping: sonos group status|join|unjoin|party|solo
- Favorites: sonos favorites list|open
- Queue: sonos queue list|play|clear
- Spotify search via SMAPI: sonos smapi search --service "Spotify" --category tracks "query"
sonos group status
sonos favorites list
sonos queue list
sonos smapi search --service "Spotify" --category tracks "query"Fix discovery errors: no route to host and bind not permitted
If discovery fails, the skill includes troubleshooting for two errors. The first is a 'no route to host' error during sonos discover. On macOS in direct mode (no Docker sandbox), the source says Local Network access must be enabled under Settings → Privacy & Security → Local Network for the top-level host process. That process is node if run via launchd, Terminal if run directly in a terminal, or Visual Studio Code if run from VS Code's terminal. The alternative is running the agent in a sandbox (Docker container) with network access allowed.
The second error is 'bind: operation not permitted'. This usually means the agent is running in a sandbox that blocks network access. If discovery still fails, use the --ip flag with your speaker's IP address, which the source recommends when SSDP fails.
- no route to host: enable Local Network for the host process, or allow network access for a Docker sandbox
- bind: operation not permitted: the sandbox blocks network access, so allow the escalation request or run outside the sandbox
- SSDP failure: pass --ip <speaker-ip>
sonos discover
sonos status --ip <speaker-ip>What people use it for
- Checking what is playing in each room before leaving home
- Setting a speaker's volume by asking the agent in a chat
- Grouping rooms for a party or ungrouping them afterwards
- Browsing favorites or managing the queue without opening an app
- Searching Spotify through Sonos, if Spotify credentials are configured
Frequently asked questions
How do I install the sonoscli agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills. You also need the sonos tool, which the source installs with go install github.com/steipete/sonoscli/cmd/sonos@latest.
What do I need to run the sonoscli skill?
You need Sonos speakers on your local network, the sonos command-line tool, and a Go toolchain for the install step. The skill runs scripts and uses the network. Spotify search is optional and needs SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET.
Is the sonoscli skill free?
The skill is listed under the MIT licence. The source does not state pricing for the skill or the sonos tool, so check the project repository for licence details.
Why does sonos discover say 'no route to host' on my Mac?
In direct mode on macOS, the host process needs Local Network permission. Go to Settings → Privacy & Security → Local Network and enable it for node (launchd), Terminal, or Visual Studio Code, depending on how you run the agent. Alternatively, run the agent in a Docker sandbox with network access allowed.
What does 'bind: operation not permitted' mean?
It usually means the agent is running in a sandbox that does not allow network access. Allow the escalation request when prompted, or run the command outside the sandbox, then try discovery again.
What if discovery fails and I cannot fix the network permissions?
The skill notes that if SSDP discovery fails you can specify your speaker's address directly with --ip <speaker-ip>. Find the IP in your router or Sonos app, then ask the agent to use it.
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
This skill suits Sonos owners who want to control playback, volume and grouping by asking an AI agent, and developers already comfortable with the sonos CLI. It is not useful without Sonos hardware on your local network, and it will struggle in sandboxes that block network access. If your environment restricts networking, expect to spend time on permissions first.
Download the skill