Sonoscli
Let your coding agent discover and control Sonos speakers on the LAN for play, volume, grouping, queue, and Spotify SMAPI search.
Overview
Sonoscli is an agent skill for the Build phase that controls Sonos speakers on the local network through the sonos CLI.
Install
npx skills add https://github.com/steipete/clawdis --skill sonoscliWhat is this skill?
- Discover speakers and read status with sonos discover and sonos status --name
- Transport controls: play, pause, stop with named room targeting
- Volume, grouping (join, unjoin, party, solo), favorites, and queue list/play/clear
- Spotify catalog search via sonos smapi search when SMAPI is available
- Fallback --ip when SSDP discovery fails; optional Spotify Web API credentials documented separately
- Documents SSDP fallback via --ip when discover fails
- Covers grouping, favorites, queue, and SMAPI search command families
Adoption & trust: 2k installs on skills.sh; 378k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want your agent to play, pause, or group Sonos rooms without manually typing discovery and SMAPI commands every time.
Who is it for?
Solo builders automating a home or studio Sonos setup from Claude Code, Cursor, or similar agents with Go-installed sonoscli.
Skip if: Production multi-tenant streaming products, cloud-only audio pipelines, or environments without LAN access to Sonos hardware.
When should I use this skill?
You need to discover, play, pause, set volume, group, or queue Sonos speakers via the sonos CLI on the local network.
What do I get? / Deliverables
The agent runs documented sonos commands for status, transport, volume, queues, and search with SSDP or --ip fallbacks when discovery fails.
- Executed sonos CLI commands with speaker state or playback outcome
- Troubleshooting guidance when discovery or Spotify optional paths fail
Recommended Skills
Journey fit
This skill wires a local hardware CLI into agent workflows, which Prism catalogs under Build integrations for callable tools. Integrations fits packaged CLIs that extend what the agent can operate on your network, distinct from app feature code.
How it compares
LAN CLI integration skill, not a hosted Sonos API wrapper or smart-home MCP server.
Common Questions / FAQ
Who is sonoscli for?
Indie builders and power users who already have Sonos on the network and want repeatable agent instructions for the sonos binary.
When should I use sonoscli?
Use it during Build when wiring agent automations that need speaker discovery, room playback, grouping, or queue control on your local network.
Is sonoscli safe to install?
It issues local network commands to speakers you own; review the Security Audits panel on this Prism page and treat Spotify secrets as sensitive if you enable optional Web API search.
SKILL.md
READMESKILL.md - Sonoscli
# Sonos CLI Use `sonos` to control Sonos speakers on the local network. ## Quick start - `sonos discover` - `sonos status --name "Kitchen"` - `sonos play|pause|stop --name "Kitchen"` - `sonos volume set 15 --name "Kitchen"` ## Common tasks - 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"` ## Notes - If SSDP fails, specify `--ip <speaker-ip>`. - Spotify Web API search is optional and requires `SPOTIFY_CLIENT_ID/SECRET`. - If there is an error, check the troubleshooting section and offer advice if there is a decent match. ## Troubleshooting ### `sonos discover` - `no route to host` - On error `Error: write udp4 0.0.0.0:64326->239.255.255.250:1900: sendto: no route to host (Command exited with code 1)` - Note that the port number after `0.0.0.0:` is ephemeral and will change and the netmask may not match exactly either - The `sendto: no route to host` should stay consistent - Advise the user that in `direct` (no Docker sandbox) mode on Mac OS that Settings -> Privacy & Security -> Local Network will need to be enabled for the top-level host parent process of the Gateway - `node` if running via `launchd` - `Terminal` if running the gateway directly in the terminal - `Visual Studio Code` if running via terminal in VS Code - An alternative option is to use `sandbox` (docker container) with network access allowed for that sandbox ### `sonos discover` - `bind: operation not permitted` - On error `Error: listen udp4 0.0.0.0:0: bind: operation not permitted` - Advise the user that they may be running via a Codex or other sandbox that does not permit network access (this can be replicated by running `sonos discover` within a Codex CLI session with sandbox enabled and not approving the escalation request)