Sonos CLI Skill
Control Philips Hue lights via the sonos CLI command-line interface installed at /opt/homebrew/bin/sonos (v0.1.1+).
Known Speakers
Two speakers are configured in this household:
| Speaker |
IP Address |
Notes |
| Kitchen |
192.168.68.61 |
Primary speaker, default target |
| TV |
192.168.68.60 |
Secondary speaker |
To re-discover speakers or add new ones, run:
sonos discover
If a speaker becomes unreachable, check network connectivity and re-run discover.
Core Workflow
When the user mentions Sonos or a speaker name:
- Identify the target speaker — infer from context ("kitchen", "tv", "living room"), or default to Kitchen if ambiguous.
- Map intent to command — use the command map below to translate natural language into CLI syntax.
- Execute the command — run
sonos <cmd> --name "<Room>" (unless a defaultRoom is configured).
- Confirm or display output — for status/volume queries, show the parsed result; for mutations (play, pause, set), confirm what was done with a short message.
- Handle errors gracefully — if the speaker is unreachable, suggest running
sonos discover or checking network status.
Command Reference
Status & Info
| User Intent |
CLI Command |
Output |
| What's playing? |
sonos status --name "<Room>" |
Current track, artist, duration, playback state |
| Get volume |
sonos volume get --name "<Room>" |
Current volume (0–100) |
| List speakers |
sonos discover |
All speakers on network with IPs |
| Show queue |
sonos queue list --name "<Room>" --format json |
Full playlist (JSON) |
| List favorites |
sonos favorites list --name "<Room>" --format json |
Saved favorites (JSON) |
Playback Control
| User Intent |
CLI Command |
| Play / resume |
sonos play --name "<Room>" |
| Pause |
sonos pause --name "<Room>" |
| Stop |
sonos stop --name "<Room>" |
| Skip / next |
sonos next --name "<Room>" |
| Previous track |
sonos prev --name "<Room>" |
Volume Control
| User Intent |
CLI Command |
| Set volume to N (0–100) |
sonos volume set <N> --name "<Room>" |
| Mute |
sonos mute on --name "<Room>" |
| Unmute |
sonos mute off --name "<Room>" |
| Toggle mute |
sonos mute toggle --name "<Room>" |
| Increase by N |
sonos volume +<N> --name "<Room>" |
| Decrease by N |
sonos volume -<N> --name "<Room>" |
Music Playback
Spotify via SMAPI (Preferred — no credentials)
sonos play spotify "<query>" --name "<Room>"
--category tracks|albums|playlists — filter search type (default: all)--index N — pick Nth result (0-based; default: 0 for top result)
Examples:
sonos play spotify "jazz" --name "Kitchen" — play jazz mixsonos play spotify "norah jones" --category tracks --index 2 --name "Kitchen" — play 3rd track by Norah Jones
Spotify via Web API (if SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET are set)
sonos search spotify "<query>" --type track --open --name "<Room>"
Prefer SMAPI above unless the user explicitly says "search."
Grouping & Party Mode
| User Intent |
CLI Command |
| Group Kitchen + TV |
sonos group join --name "Kitchen" --to "TV" |
| Ungroup / solo speaker |
sonos group solo --name "<Room>" |
| Party mode (all rooms join Kitchen) |
sonos group party --to "Kitchen" |
Favorites & Scenes
| User Intent |
CLI Command |
| Play saved favorite |
sonos favorites open "<favorite-name>" --name "<Room>" |
| Save current state as scene |
sonos scene save "<scene-name>" |
| Apply a saved scene |
sonos scene apply "<scene-name>" |
Advanced
| User Intent |
CLI Command |
| Clear queue |
sonos queue clear --name "<Room>" |
| TV audio input |
sonos tv --name "TV" |
| Play radio/stream URL |
sonos play-uri <url> --name "<Room>" --radio --title "<display-name>" |
Example Interactions
1. Play Music on a Speaker
User: "Play some jazz on the kitchen"
Skill:
- Target: Kitchen
- Intent: play music (Spotify)
- Command:
sonos play spotify "jazz" --name "Kitchen"
- Response:
Playing jazz on Kitchen speaker
2. Adjust Volume
User: "Turn the TV speaker up to 50"
Skill:
- Target: TV
- Intent: set volume
- Command:
sonos volume set 50 --name "TV"
- Response:
TV volume set to 50
3. Check What's Playing
User: "What's playing on Sonos?"
Skill:
- Target: Kitchen (default)
- Intent: status query
- Command:
sonos status --name "Kitchen"
- Response:
[Parsed output] Artist - Track Name (2:45 / 5:30) [Playing]
4. Group Speakers
User: "Group my speakers together"
Skill:
- Infer primary coordinator (Kitchen)
- Intent: party mode (group all)
- Command:
sonos group party --to "Kitchen"
- Response:
TV grouped with Kitchen
5. Pause Playback
User: "Pause the Sonos"
Skill:
- Target: Kitchen (default)
- Intent: pause
- Command:
sonos pause --name "Kitchen"
- Response:
Paused
Output Handling
Queries (status, volume, queue, favorites):
- Run command with
--format json if available
- Parse JSON output and present cleanly to the user
- Example:
sonos status --format json → extract track, artist, duration, playback and format as human-readable text
Mutations (play, pause, volume set, grouping):
- Run command without
--format json
- Confirm action with a brief message:
"Playing [title] on Kitchen" or "Volume set to 50"
Errors:
- If speaker is unreachable:
"Kitchen is offline. Try 'sonos discover' to re-scan the network."
- If command fails: show CLI error verbatim + suggest fix
- If Spotify search returns no results:
"No tracks found for 'xyz'. Try a different search."
Skill Trigger
Only invoke this skill when the user explicitly mentions:
Sonos, sonos (case-insensitive)- Speaker names:
Kitchen, TV, or other rooms
- Commands tied to those speakers:
"play music on the kitchen speaker", "turn up volume" in a Sonos context
Do NOT trigger if the user says "play music" without mentioning Sonos or a specific speaker name. This keeps the skill focused and avoids false positives.
Notes & Troubleshooting
- Default speaker: Kitchen is the default if ambiguous (e.g.
"pause Sonos" → pauses Kitchen)
- Multi-speaker commands: Always target explicitly or confirm with the user which speaker to control
- Network issues: If speakers go offline, run
sonos discover to re-scan
- Spotify setup: SMAPI (via
sonos play spotify) doesn't require credentials; use Web API (via sonos search spotify) only if user has Spotify API keys configured
- Favorites: User must have saved favorites in their Sonos app first; the CLI can then reference them by name
1---2name: sonos-cli3description: Control Sonos speakers from the CLI using the `sonos` command. Translates natural language requests into sonos CLI commands for playback, volume, grouping, queue management, and music search. Use this skill whenever the user mentions Sonos, asks to play music on a speaker, control volume on a room, group or ungroup speakers, manage their Sonos queue, or references speaker names like "Kitchen" or "TV". Trigger phrases: "play X on Sonos", "turn up the kitchen speaker", "pause Sonos", "what's playing on Sonos", "group my speakers", "play my Sonos favorites", "Sonos volume", "skip track on Sonos", "add to Sonos queue".4---56# Sonos CLI Skill78Control Philips Hue lights via the `sonos` CLI command-line interface installed at `/opt/homebrew/bin/sonos` (v0.1.1+).910## Known Speakers1112Two speakers are configured in this household:1314| Speaker | IP Address | Notes |15|---------|-----------|-------|16| Kitchen | 192.168.68.61 | Primary speaker, default target |17| TV | 192.168.68.60 | Secondary speaker |1819To re-discover speakers or add new ones, run:20```bash21sonos discover22```2324If a speaker becomes unreachable, check network connectivity and re-run `discover`.2526---2728## Core Workflow2930When the user mentions Sonos or a speaker name:31321. **Identify the target speaker** — infer from context ("kitchen", "tv", "living room"), or default to **Kitchen** if ambiguous.332. **Map intent to command** — use the command map below to translate natural language into CLI syntax.343. **Execute the command** — run `sonos <cmd> --name "<Room>"` (unless a defaultRoom is configured).354. **Confirm or display output** — for status/volume queries, show the parsed result; for mutations (play, pause, set), confirm what was done with a short message.365. **Handle errors gracefully** — if the speaker is unreachable, suggest running `sonos discover` or checking network status.3738---3940## Command Reference4142### Status & Info4344| User Intent | CLI Command | Output |45|---|---|---|46| What's playing? | `sonos status --name "<Room>"` | Current track, artist, duration, playback state |47| Get volume | `sonos volume get --name "<Room>"` | Current volume (0–100) |48| List speakers | `sonos discover` | All speakers on network with IPs |49| Show queue | `sonos queue list --name "<Room>" --format json` | Full playlist (JSON) |50| List favorites | `sonos favorites list --name "<Room>" --format json` | Saved favorites (JSON) |5152### Playback Control5354| User Intent | CLI Command |55|---|---|56| Play / resume | `sonos play --name "<Room>"` |57| Pause | `sonos pause --name "<Room>"` |58| Stop | `sonos stop --name "<Room>"` |59| Skip / next | `sonos next --name "<Room>"` |60| Previous track | `sonos prev --name "<Room>"` |6162### Volume Control6364| User Intent | CLI Command |65|---|---|66| Set volume to N (0–100) | `sonos volume set <N> --name "<Room>"` |67| Mute | `sonos mute on --name "<Room>"` |68| Unmute | `sonos mute off --name "<Room>"` |69| Toggle mute | `sonos mute toggle --name "<Room>"` |70| Increase by N | `sonos volume +<N> --name "<Room>"` |71| Decrease by N | `sonos volume -<N> --name "<Room>"` |7273### Music Playback7475#### Spotify via SMAPI (Preferred — no credentials)7677```bash78sonos play spotify "<query>" --name "<Room>"79```8081- `--category tracks|albums|playlists` — filter search type (default: all)82- `--index N` — pick Nth result (0-based; default: 0 for top result)8384Examples:85- `sonos play spotify "jazz" --name "Kitchen"` — play jazz mix86- `sonos play spotify "norah jones" --category tracks --index 2 --name "Kitchen"` — play 3rd track by Norah Jones8788#### Spotify via Web API (if SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET are set)8990```bash91sonos search spotify "<query>" --type track --open --name "<Room>"92```9394_Prefer SMAPI above unless the user explicitly says "search."_9596### Grouping & Party Mode9798| User Intent | CLI Command |99|---|---|100| Group Kitchen + TV | `sonos group join --name "Kitchen" --to "TV"` |101| Ungroup / solo speaker | `sonos group solo --name "<Room>"` |102| Party mode (all rooms join Kitchen) | `sonos group party --to "Kitchen"` |103104### Favorites & Scenes105106| User Intent | CLI Command |107|---|---|108| Play saved favorite | `sonos favorites open "<favorite-name>" --name "<Room>"` |109| Save current state as scene | `sonos scene save "<scene-name>"` |110| Apply a saved scene | `sonos scene apply "<scene-name>"` |111112### Advanced113114| User Intent | CLI Command |115|---|---|116| Clear queue | `sonos queue clear --name "<Room>"` |117| TV audio input | `sonos tv --name "TV"` |118| Play radio/stream URL | `sonos play-uri <url> --name "<Room>" --radio --title "<display-name>"` |119120---121122## Example Interactions123124### 1. Play Music on a Speaker125126**User:** "Play some jazz on the kitchen"127128**Skill:**129- Target: Kitchen130- Intent: play music (Spotify)131- Command: `sonos play spotify "jazz" --name "Kitchen"`132- Response: `Playing jazz on Kitchen speaker`133134### 2. Adjust Volume135136**User:** "Turn the TV speaker up to 50"137138**Skill:**139- Target: TV140- Intent: set volume141- Command: `sonos volume set 50 --name "TV"`142- Response: `TV volume set to 50`143144### 3. Check What's Playing145146**User:** "What's playing on Sonos?"147148**Skill:**149- Target: Kitchen (default)150- Intent: status query151- Command: `sonos status --name "Kitchen"`152- Response: `[Parsed output] Artist - Track Name (2:45 / 5:30) [Playing]`153154### 4. Group Speakers155156**User:** "Group my speakers together"157158**Skill:**159- Infer primary coordinator (Kitchen)160- Intent: party mode (group all)161- Command: `sonos group party --to "Kitchen"`162- Response: `TV grouped with Kitchen`163164### 5. Pause Playback165166**User:** "Pause the Sonos"167168**Skill:**169- Target: Kitchen (default)170- Intent: pause171- Command: `sonos pause --name "Kitchen"`172- Response: `Paused`173174---175176## Output Handling177178**Queries (status, volume, queue, favorites):**179- Run command with `--format json` if available180- Parse JSON output and present cleanly to the user181- Example: `sonos status --format json` → extract `track`, `artist`, `duration`, `playback` and format as human-readable text182183**Mutations (play, pause, volume set, grouping):**184- Run command without `--format json`185- Confirm action with a brief message: `"Playing [title] on Kitchen"` or `"Volume set to 50"`186187**Errors:**188- If speaker is unreachable: `"Kitchen is offline. Try 'sonos discover' to re-scan the network."`189- If command fails: show CLI error verbatim + suggest fix190- If Spotify search returns no results: `"No tracks found for 'xyz'. Try a different search."`191192---193194## Skill Trigger195196**Only invoke this skill when the user explicitly mentions:**197- `Sonos`, `sonos` (case-insensitive)198- Speaker names: `Kitchen`, `TV`, or other rooms199- Commands tied to those speakers: `"play music on the kitchen speaker"`, `"turn up volume"` in a Sonos context200201**Do NOT trigger if** the user says `"play music"` without mentioning Sonos or a specific speaker name. This keeps the skill focused and avoids false positives.202203---204205## Notes & Troubleshooting206207- **Default speaker:** Kitchen is the default if ambiguous (e.g. `"pause Sonos"` → pauses Kitchen)208- **Multi-speaker commands:** Always target explicitly or confirm with the user which speaker to control209- **Network issues:** If speakers go offline, run `sonos discover` to re-scan210- **Spotify setup:** SMAPI (via `sonos play spotify`) doesn't require credentials; use Web API (via `sonos search spotify`) only if user has Spotify API keys configured211- **Favorites:** User must have saved favorites in their Sonos app first; the CLI can then reference them by name212
conorluddy