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:
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"