playbooks

home / skills / openclaw / skills / sonoscli

sonoscli skill

/skills/steipete/sonoscli

This skill helps you control Sonos speakers on your network, discover status, and manage playback and volume via a CLI.

This is most likely a fork of the sonos skill from openclaw
npx playbooks add skill openclaw/skills --skill sonoscli

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
940 B
---
name: sonoscli
description: Control Sonos speakers (discover/status/play/volume/group).
homepage: https://sonoscli.sh
metadata: {"clawdbot":{"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`.

Overview

This skill provides a command-line interface to discover and control Sonos speakers on your local network. It exposes status checks, playback controls, volume adjustments, grouping, favorites, queues, and optional Spotify search integration. Use it to automate or script common Sonos actions from terminals or CI tasks.

How this skill works

The tool scans the local network for Sonos devices via SSDP and talks to each speaker using the Sonos control APIs. Commands let you query status, control playback, change volume, manage groups, manipulate the queue, and access favorites. If discovery fails you can target a speaker by IP, and optional Spotify Web API credentials enable richer search via SMAPI.

When to use it

  • Automating Sonos actions from scripts or cron jobs
  • Quickly checking speaker status or playback from a terminal
  • Grouping speakers for synchronized playback or breaking groups
  • Managing queues and favorites without a GUI app
  • Running searches on Spotify when SPOTIFY_CLIENT_ID/SECRET are available

Best practices

  • Use discovery for convenience but pass --ip when SSDP is unreliable
  • Provide speaker names exactly as reported by status to avoid ambiguity
  • Use group commands (join/party/solo) to manage multi-room setups safely
  • Keep Spotify credentials out of source control and set them as environment variables
  • Test commands like queue clear or group unjoin on a single device before broad changes

Example use cases

  • Discover all Sonos devices and list their playback status
  • Set volume to 15 for the Kitchen speaker: volume set 15 --name "Kitchen"
  • Group Living Room and Bedroom for party playback: sonos group join
  • Search Spotify tracks and play a result when SPOTIFY_CLIENT_ID/SECRET are configured
  • List and open saved favorites or clear the current queue before a new playlist

FAQ

Discovery fails, what should I do?

If SSDP discovery fails, run commands with --ip <speaker-ip> to target a specific speaker directly.

How do I enable Spotify search?

Set SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET as environment variables; the SMAPI search will then be available for the Spotify service.