SonosCLI — OpenClaw Skill

What This Skill Does

The SonosCLI skill gives your OpenClaw agent full control over Sonos speakers on your local network. Using the sonos CLI, your agent can discover speakers, check playback status, play/pause/stop music, adjust volume, manage speaker groups, browse favorites, manipulate the queue, and even search Spotify via the Sonos Music API (SMAPI).

The skill uses SSDP to automatically discover Sonos devices, so there is no manual IP configuration needed in most setups. You can target specific speakers by name or fall back to direct IP addressing if SSDP discovery has issues on your network. All commands support JSON output for scripted workflows.

This is a great fit for home automation scenarios where you want your AI agent to control music playback, set up multi-room audio, or respond to voice requests like "play jazz in the kitchen at volume 15." The skill pairs naturally with other media skills for a complete smart-home audio experience.

Example Prompts

Play some jazz music in the Kitchen at volume 20

What's currently playing on the Living Room speaker?

Group all speakers together for the party and set volume to 30

Pause music in every room

Search Spotify for "lo-fi beats" and play the first result on the Bedroom speaker

Lower the Office speaker volume to 10 -- I'm on a call

Show me what Sonos speakers are on the network right now

Ungroup the Bedroom speaker so it plays independently

Requirements

Binary dependency: sonos must be installed and available in PATH.

• Install via Go: go install github.com/steipete/sonoscli/cmd/sonos@latest
• Network access: The agent must be on the same local network as the Sonos speakers (SSDP multicast)
• Optional: SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET for Spotify search via SMAPI

Setup on KiwiClaw

SonosCLI requires local network access to communicate with your Sonos speakers, so it works best with the KiwiClaw Chrome Extension bridge. Configure the extension in your KiwiClaw dashboard to route Sonos commands through your local machine.

Setup Self-Hosted

1. Install the sonos CLI: go install github.com/steipete/sonoscli/cmd/sonos@latest
2. Verify discovery works: sonos discover
3. If SSDP fails, grant Local Network permission in macOS Privacy settings for your terminal app
4. Optionally set SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET for Spotify search

Related Skills

• BluCLI -- similar speaker control for Bluesound/NAD players
• Eightctl -- smart home control for Eight Sleep pods
• Sag -- generate TTS audio, then play it on Sonos speakers
• Songsee -- visualize the audio your Sonos speakers are playing

FAQ

How does SonosCLI discover Sonos speakers?

SonosCLI uses SSDP (Simple Service Discovery Protocol) to find Sonos devices on your local network. Run sonos discover to list all available speakers. If SSDP fails due to network configuration, you can specify a speaker IP directly with the --ip flag.

Can SonosCLI search and play from Spotify?

Yes. SonosCLI includes Spotify search via SMAPI (Sonos Music API). Use sonos smapi search --service "Spotify" --category tracks "query" to search. This requires optional SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET environment variables.

Does SonosCLI work inside a Docker container?

SonosCLI requires network access to discover and communicate with Sonos speakers. In Docker/sandbox environments, network access must be permitted. If you get a "bind: operation not permitted" error, the sandbox is blocking network access.

Can I group and ungroup speakers with SonosCLI?

Yes. Use sonos group status to see current groupings, sonos group join to add a speaker to a group, sonos group party to group all speakers, and sonos group solo to ungroup a speaker.