sonoscli

steipete/clawdis

Control Sonos speakers on your local network—discover, play, pause, adjust volume, and group speakers.

What is sonoscli?

sonoscli is a command-line tool for discovering and controlling Sonos speakers on the local network. Use it to manage playback, volume, grouping, favorites, and queue across your Sonos system.

Discover Sonos speakers on the network
Check speaker status and current playback
Play, pause, and stop audio
Adjust volume and mute
Group/ungroup speakers or create party mode
Manage queue and favorites

How to install sonoscli

npx skills add https://github.com/steipete/clawdis --skill sonoscli

Prerequisites

Go installed (for building from source)
Sonos speakers on the same local network
Optional: Spotify API credentials (SPOTIFY_CLIENT_ID/SECRET) for Spotify search

Claude Code

Cursor

Windsurf

Cline

How to use sonoscli

1.Run `sonos discover` to find speakers on your network
2.Use `sonos status --name "Kitchen"` to check a speaker's current state
3.Control playback with `sonos play|pause|stop --name "Kitchen"`
4.Adjust volume with `sonos volume set 15 --name "Kitchen"`
5.Manage groups with `sonos group join|unjoin|party|solo`
6.List and manage queue with `sonos queue list|play|clear`
7.If SSDP discovery fails, specify speaker IP directly with `--ip <speaker-ip>`

Use cases

Good for

Automate speaker control in scripts or workflows
Discover available speakers and their IP addresses
Control kitchen or living room speakers by name
Create speaker groups for synchronized playback
Search and queue Spotify tracks programmatically

Who it's for

Home automation enthusiasts
Developers building Sonos integrations
System administrators managing multi-room audio
Anyone scripting speaker control via CLI

sonoscli FAQ

What should I do if `sonos discover` fails with 'no route to host'?

On macOS, check Settings → Privacy & Security → Local Network and enable access for the parent process (node, Terminal, or VS Code). Alternatively, run the tool in a Docker sandbox with network access enabled.

What does 'bind: operation not permitted' mean?

This error occurs when running in a restricted sandbox (like Codex) that doesn't permit network access. Approve the escalation request or run outside the sandbox.

Do I need Spotify credentials?

No, Spotify credentials are optional. They're only needed if you want to search Spotify via the `sonos smapi search` command.

Can I control speakers by IP instead of name?

Yes, use the `--ip <speaker-ip>` flag if SSDP discovery fails or you prefer direct IP addressing.

How do I create a speaker group?

Use `sonos group join --name "Speaker1" --target "Speaker2"` to join speakers, or `sonos group party` to group all speakers together.

Full instructions (SKILL.md)

Source of truth, from steipete/clawdis.

name: sonoscli description: "Control Sonos speakers (discover/status/play/volume/group)." homepage: https://sonoscli.sh metadata: { "openclaw": { "emoji": "🔊", "requires": { "bins": ["sonos"] }, "install": [ { "id": "go", "kind": "go", "module": "github.com/steipete/sonoscli/cmd/sonos@latest", "bins": ["sonos"], "label": "Install sonoscli (go)", }, ], }, }

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)