| name | spotify |
| description | Control Spotify playback: play, pause, skip, search tracks/albums/playlists, manage devices and queue via spogo CLI. |
| requires_bridge | spotify |
Spotify
Use the spotify bridge to control Spotify playback via spogo on the host.
When to Use
- User asks to play, pause, skip music
- Searching for songs, albums, artists, playlists
- Managing playback devices or queue
- Checking what's currently playing
When NOT to Use
- Apple Music -> not supported
- Sonos playback -> use sonos bridge
- Local audio files -> not supported
Critical Rules
- Only run
spogo commands through host_execute. Never run sleep, echo, or any non-spogo command through the spotify bridge — they will be blocked by the gateway allowlist.
- Always verify playback after
spogo play — run spogo status --json and check that is_playing is true and the correct track is loaded. Never tell the user "it's playing" without verifying.
- Use
--device flag when targeting a specific device, especially if spogo play fails with "missing device id".
Commands
All commands run via host_execute(bridge="spotify", command="...").
Play by Name (most common workflow)
IMPORTANT: spogo play requires a Spotify URI, not a name. Follow this exact sequence:
- Search:
spogo search track "song name" --json (or artist/album/playlist)
- Extract the
uri field from the first result
- Play:
spogo play <uri>
- Verify:
spogo status --json — check is_playing: true and correct track name
- If
is_playing: false, see "Known Issues" below
Playback
spogo status # What's playing (text)
spogo status --json # What's playing (JSON, use for verification)
spogo play <uri> # Play a specific URI
spogo play <uri> --device "MacBook Air" # Play on a specific device
spogo pause # Pause
spogo next # Next track
spogo prev # Previous track
Search
Always use --json to get URIs for playback.
spogo search track "bohemian rhapsody" --json
spogo search album "dark side of the moon" --json
spogo search artist "radiohead" --json
spogo search playlist "chill vibes" --json
Devices
spogo device list --json # List devices (use JSON to check is_active)
spogo device set "Living Room" # Switch device
Auth & Diagnostics
spogo auth status # Check if authenticated
spogo auth import --browser chrome # Import cookies from Chrome
spogo auth import --browser safari # Import cookies from Safari
Known Issues & Workarounds
Device not active after Spotify restart
After Spotify restarts, all devices show is_active: false. In this state:
spogo play <uri> returns "Playback started" but does nothing (false success)- Playback only works after the user manually interacts with Spotify at least once
Detection: After spogo play <uri>, run spogo status --json. If is_playing is still false or the track didn't change, the device is not active.
Workaround: Tell the user: "Spotify needs to be activated first — press play once in the Spotify app, then I can take over."
Resume (spogo play without args) returns 403
spogo play (resume) often fails with 403 Forbidden. This is a spogo/Spotify API bug.
Workaround: Never use spogo play without arguments. Instead:
- Get current track:
spogo status --json
- Replay with URI:
spogo play <item.uri>
"missing device id" error
Happens when no device is active and spogo can't auto-select one.
Workaround:
- Run
spogo device list --json to find available devices
- Use
--device flag: spogo play <uri> --device "Emanuele's MacBook Air"
- If all devices are
is_active: false, tell the user to open Spotify and press play once
Rate limit (429)
Spotify API has rate limits. If you get a 429 error, wait a moment before retrying. Do NOT try to run sleep via host_execute — just tell the user you'll retry in a moment and try the command again on the next message.
Troubleshooting
If a Spotify command fails, follow this sequence:
- Run
spogo auth status to check authentication
- If
sp_dc cookie is missing/expired, run spogo auth import --browser chrome
- If import fails, tell the user to log out/in on
open.spotify.com in Chrome, then retry
- If Keychain popup blocks on host, tell user to click "Always Allow", then retry
- If playback returns success but nothing happens, run
spogo device list --json — if all is_active: false, tell user to activate Spotify manually once
- If rate limited (429), wait and retry on the next message
Always try via host_execute first. Only suggest manual steps if host_execute itself fails.
Setup (first time, on host)
- Requires Spotify Premium account
- Install:
brew install steipete/tap/spogo
- Initial auth:
spogo auth import --browser chrome (or let Ciana do it)
- If Keychain popup appears, enter password and click "Always Allow"
