sonoscli Skill: Control Every Sonos Speaker on Your Network From the Terminal

23,000+ downloads and 16 stars — sonoscli is a focused skill that does one thing well: give Claude complete command-line control over Sonos speakers. If you have Sonos speakers on your local network and use Claude Code, this skill lets you issue audio commands as naturally as any other terminal operation.

Built by @steipete (Peter Steinberger), it wraps the sonos CLI — a Go binary that communicates directly with Sonos speakers over the local network using their native API.

The Problem It Solves

Sonos has a good app, but an app requires context-switching. When you're in a terminal session — working, debugging, running scripts — reaching for your phone to adjust the music breaks the flow. And if you want to automate audio as part of a larger workflow (set the mood for a work session, cut audio when a build fails, group all speakers for a meeting announcement), the app doesn't help.

sonoscli brings Sonos control into the same space where everything else happens.

Quick Start

# See what speakers are on the network
sonos discover
 
# Check status of a specific speaker
sonos status --name "Kitchen"
 
# Basic playback
sonos play --name "Kitchen"
sonos pause --name "Kitchen"
sonos stop --name "Kitchen"
 
# Volume control
sonos volume set 15 --name "Kitchen"

The --name flag accepts the speaker's display name as it appears in the Sonos app.

Speaker Grouping

Multi-room audio via the command line:

# Check current group topology
sonos group status
 
# Group speakers together
sonos group join --name "Living Room" --coordinator "Kitchen"
 
# Remove from group
sonos group unjoin --name "Living Room"
 
# Party mode (all speakers play together)
sonos group party
 
# Solo mode (current speaker leaves all groups)
sonos group solo

party and solo are the most useful for quick whole-home or single-room toggles.

Favorites and Queue

# List saved favorites (playlists, radio stations, etc.)
sonos favorites list
 
# Play a favorite
sonos favorites open "Morning Playlist"
 
# Queue management
sonos queue list
sonos queue play 3    # play item at position 3
sonos queue clear

Favorites are the same ones in the Sonos app, so anything you've saved there is accessible here.

Spotify Search via SMAPI

Direct Spotify search without leaving the terminal (requires SMAPI configuration):

# Search for tracks
sonos smapi search --service "Spotify" --category tracks "Radiohead"
 
# Search for albums
sonos smapi search --service "Spotify" --category albums "OK Computer"
 
# Search for artists
sonos smapi search --service "Spotify" --category artists "Radiohead"

Note: This uses Sonos's SMAPI (Sonos Music API) integration, which is different from the Spotify Web API. It works through Sonos's built-in Spotify connection, not a separate Spotify API key.

The optional Spotify Web API integration (for SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET) provides additional search capabilities but isn't required for basic SMAPI search.

Network Discovery Notes

SSDP (Simple Service Discovery Protocol) is how the sonos binary finds speakers automatically. On most home networks this works out of the box:

sonos discover

If SSDP fails (firewall blocking multicast, corporate network, VPN), specify the speaker IP directly:

sonos status --ip 192.168.1.105

How to Install

clawhub install sonoscli

The underlying sonos binary is installed via Go:

go install github.com/steipete/sonoscli/cmd/sonos@latest

Or if you have Go via Homebrew:

brew install go && go install github.com/steipete/sonoscli/cmd/sonos@latest

Practical Tips

1. Speaker names must match exactly — Use sonos discover first to see the exact names as registered in your Sonos system. Capitalization and spacing matter.

2. Group before playing favorites — If you want whole-home audio, sonos group party first, then sonos favorites open "playlist". This ensures all speakers start together rather than sequentially.

3. Volume set vs. adjust — sonos volume set 15 sets an absolute level. For relative adjustments (turn up a bit), check if the CLI supports increment syntax or use two calls: status to check current, then set to target level.

4. SSDP unreliable? Note the IPs — Run sonos discover on a reliable network, note each speaker's IP, and create aliases or scripts with --ip flags for deterministic targeting.

5. Combine with other automation — sonoscli pairs well with shell scripts, cron jobs, or other Claude workflows. Examples: fade out when work session ends, all-speaker announcement before standup, cut audio when tests start running.

Comparison: sonoscli vs Alternatives

Considerations

• Local network only — sonoscli works over SSDP on the local network. It doesn't work remotely without a VPN or proxy.
• Speaker names are case-sensitive — Typos and capitalization mismatches will cause "speaker not found" errors.
• SMAPI varies by Sonos account — Spotify SMAPI search requires that Spotify is connected in your Sonos account. Other services (Apple Music, Amazon Music) work similarly.
• Go required — The binary is installed via go install. If Go isn't available, installation requires setting it up first.

The Bigger Picture

Smart home audio control from the terminal is a niche use case — but for developers who live in the terminal, it's the right abstraction. sonoscli treats your Sonos system the same way other skills treat GitHub or databases: as a resource you interact with through commands, not through context-switching to a separate interface.

For automation, home scripts, or just keeping your hands on the keyboard, it fills a gap that no other tool addresses in this form.

View the skill on ClawHub: sonoscli