---
name: "spotify"
description: "Discover, search, and manage Spotify music, audiobooks, podcasts, and playlists, including deleting shows or episodes you created with Save to Spotify."
metadata: { "includeInPrompt": true }
---
# Spotify
## Purpose
Use `spotify-api` to browse personalized Spotify content, search for music, audiobooks, and podcasts, manage the user's library and playlists, check saveability of items, and start or control Spotify playback. For new playback during a voice conversation, follow **Voice playback** below. Use `save-to-spotify` to manage shows and episodes you created through Save to Spotify.
## Voice playback
Use this section only when someone asks by voice, on a call, to start new music, a podcast or episode, or an audiobook. For pause, resume, stop, skip, previous, status, volume, transfer, queue, login, search, library, or playlist requests, and for any typed request, use the `spotify-api` commands below.
### Calls from a device that lists `music_fulfillment`
When the device carrying the call lists `music_fulfillment` in the call's device catalog, follow [wearable playback](references/wearable-playback.md) instead of the rest of this section.
### Other calls
On a call from a device without `music_fulfillment`, including glasses that do not list it, play through Spotify Connect and never send `device.invoke` with `music_fulfillment` to any device. If the caller asks for another service or source, such as Apple Music or Amazon Music, say only Spotify plays here for now, offer to play it on Spotify instead, and run no command. Find the item with `spotify-api search`, or `spotify-api library` for the caller's own playlists and saved items, then start it with `spotify-api play --context-uri <uri>`. When the caller names a device, add `--target-device-id` with an ID from `spotify-api devices`. "On Spotify" names the service, not a device.
### Results
If the lookup returns `not_found`, relay `catalog_fallback.message` verbatim if present, otherwise say it wasn't found on Spotify; play nothing else.
If Spotify is not connected, follow **Auth** below.
If playback fails, report it once. Do not retry on another device or route.
If playback succeeds, do not run `spotify-api now-playing`. Acknowledge it in one short sentence naming what is playing and where, or stay silent if the call already acknowledged the request.
## Tooling
Use the installed CLI directly from `PATH`.
#### Connection
- `spotify-api status` — check OAuth connection status (`status`, `connect_url`, `disconnect_url`)
- `spotify-api disconnect` — disconnect Spotify (may return a confirmation URL)
- `spotify-api authorize-url` — get the active environment's connect URL
#### Browse & Discover
- `spotify-api experience --id <spotify_uri_or_name> [--language <lang>]` — get experience by ID (e.g. artist/album/show page). Large sections may include a `next` URL for more results.
- `spotify-api next-page --url <section_next_url> [--language <lang>]` — fetch the next pagination URL returned as `sections[].next` or `next` by a prior Spotify response. Prefer this over guessing section IDs.
#### Search
- `spotify-api search --query <text> [--search-type TRACKS,ALBUMS,ARTISTS,PLAYLISTS,EPISODES,PODCASTS,AUDIOBOOKS] [--language <lang>]`: search for content. Use `AUDIOBOOKS` for native Spotify audiobooks and `PODCASTS` to find shows (not `SHOWS` which is invalid). For an exact song or album lookup, always format the query as `"<song or album> by <artist>"` so missing originals are distinguished from covers and similarly named content. Use `experience --id <show_uri>` to list episodes of a found show.
- When an audiobook request requires search, its first search MUST pass `--search-type AUDIOBOOKS`. Never use an untyped search for an audiobook; an untyped response can omit audiobook sections even when this Spotify account has catalog access.
- Search responses include `spotify_search_url` for opening the same query directly in Spotify. When an exact requested item is unavailable, `catalog_fallback.message` is the fully rendered approved response and must be relayed verbatim; the object also provides `requested_content_label`, `requested_content_url`, `artist_name`, and `artist_url`.
#### Filter values
- Valid library/browse filter values are `ALBUMS`, `ARTISTS`, `PLAYLISTS`, `EPISODES`, `PODCASTS`, `SHOWS`, `PODCASTS_AND_SHOWS`, and `AUDIOBOOKS`.
- These filter values are content categories, not field projections. Never use field names such as `title`, `items.title`, `sections`, or `items` as `--filter` values.
- `TRACKS` is explicitly rejected for library filtering; use unfiltered `spotify-api library` or `spotify-api search --search-type TRACKS` to find tracks.
#### Library
- `spotify-api library [--filter ALBUMS|ARTISTS|PLAYLISTS|EPISODES|PODCASTS|SHOWS|PODCASTS_AND_SHOWS|AUDIOBOOKS] [--language <lang>]`: browse the user's library, including saved audiobooks with `AUDIOBOOKS`. `TRACKS` is not supported as a library filter; use unfiltered `library` or `search --search-type TRACKS` instead.
- `spotify-api save --uri <spotify_uri>`: save an item to the library (track, album, artist, show, episode, audiobook, playlist)
#### Delete Save to Spotify shows or episodes
- When the user asks to delete a podcast, show, or episode Muse added through Save to Spotify, use the installed `save-to-spotify` CLI. These are managed by the CLI, not `spotify-api`, `podcasters.spotify.com`, or `creators.spotify.com`.
- If `save-to-spotify` reports that show and episode management is unavailable, explain the limitation directly; do not ask the user to reconnect or retry.
- Always use JSON mode. Start with `save-to-spotify --json shows`; this inventory contains the shows created through Save to Spotify. Match by title and ask the user to disambiguate if more than one show matches.
- Inspect the selected show with `save-to-spotify --json shows get <show-id>`. List its episodes when needed with `save-to-spotify --json episodes --show-id <show-id>` and match episodes by title.
- To delete one episode, resolve its title and owning show unambiguously, then run
`save-to-spotify --json episodes delete <episode-id> --show-id <show-id>`.
- To delete the whole show, resolve the show unambiguously and tell the user that all of its episodes will be removed, then run `save-to-spotify --json shows delete <show-id>`. This command deletes the show and its episodes; do not delete each episode first.
- A `{"status":"deleted"}` response means Spotify accepted the deletion, but its listings can take about a minute to update. Poll the relevant inventory every 5–10 seconds for up to 60 seconds: use `episodes --show-id <show-id>` for an episode or `shows` for a show. Confirm completion only after the deleted ID is absent. If it is still listed after 60 seconds, tell the user the deletion was accepted and is still propagating; do not send the delete again.
- Show and episode IDs are internal command handles. Refer to content by title in user-facing replies. A CLI deletion removes the Spotify copy only; it does not delete Muse's local audio or an independently published RSS feed.
#### Collections (Playlists)
- `spotify-api create-collection --name <name>` — create a new playlist
- `spotify-api add-to-collection --collection-uri <uri> --uris <uri1,uri2,...> [--position-type BEFORE_UID|AFTER_UID --position-uid <uid>] [--revision-id <rev>]` — add items to a playlist
- `spotify-api update-collection --collection-uri <uri> --name <new_name>` — rename a playlist
#### Playback Control
- `spotify-api play [--context-uri <uri>] [--uid <uid>] [--target-device-id <id>]` — start playback (optionally of a specific album/playlist/context, starting from a specific item UID, on a specific device). For new playback during voice, follow **Voice playback** above first.
- `spotify-api pause` — pause playback on the active device
- `spotify-api resume` — resume paused playback on the active device
- `spotify-api skip` — skip to the next item
- `spotify-api previous` — go to the previous item
- `spotify-api seek --position-ms <ms>` — seek to a position in the currently playing item
- `spotify-api set-volume --volume-percent <0-100> [--target-device-id <id>]` — set playback volume
- `spotify-api transfer --target-device-id <id>` — transfer playback to a different device
- `spotify-api now-playing` — get the current playback state (track, progress, device, etc.)
- `spotify-api devices` — list available Spotify Connect devices
- `spotify-api get-queue` — get the current playback queue
- `spotify-api add-to-queue --item-uri <spotify_uri>` — add an item to the playback queue
#### Known unavailable or conditional commands
- `home`, `recommendations`, `check-saved`, `remove`, `section-items`, and `reorder-collection` are not exposed by `spotify-api` because they are unsupported or unreliable with the current Partner API responses/scopes. Use `search`, `library`, `experience`, `next-page`, and playlist create/add/update instead. This does not apply to shows and episodes created through Save to Spotify; delete those with `save-to-spotify` as described above.
- `play` and `add-to-queue` require an active Spotify Connect device; use `spotify-api devices` first and prefer an explicit `--target-device-id` where supported. `set-volume` should also prefer `--target-device-id`.
## Auth
`spotify-api` owns the Spotify connection workflow.
Auth contract:
- Run `spotify-api status` first.
- If not connected, run `spotify-api authorize-url`. Present the returned URL as a hyperlink with the text `[Connect to Spotify](<connect_url>)`; do not show or paste the raw URL.
- If playlist changes stop working after a reconnect, re-link so the token is minted with the latest requested scopes.
- If the user wants to disconnect, run `spotify-api disconnect`. When `disconnect_url` is present, replace `<disconnect_url>` with the returned URL and share only this Markdown link: `[Disconnect Spotify](<disconnect_url>)`; explain that the user must open it to confirm. When no URL is returned and the command succeeds, `spotify-api status` may be used to verify the disconnection.
- Do not pass secrets on the command line.
## Operating Rules
1. Verify connection with `spotify-api status` before `spotify-api` data calls. For Save to Spotify management, start with `save-to-spotify --json shows`; if it reports a token or connection error, ask the user to connect Spotify in Settings → Connections → Spotify, then retry. If it reports that management is unavailable, do not present reconnection as a fix.
2. Browse music, audiobooks, and podcasts with `search`, `library`, and `experience`. Extract relevant items; never dump full responses.
3. When a section includes `next`, call `spotify-api next-page --url <next>` to fetch additional pages. Continue following `next` until it is absent or the user has enough results.
4. The documented Save to Spotify show and episode deletions may proceed from a clear, unambiguous user request without an additional confirmation. Do not promise unsupported `spotify-api` cleanup (unsave/remove, playlist deletion, remove-from-playlist, or reordering).
5. Direct `spotify-api` playback requires an active Spotify Connect device. Immediately before setting `--target-device-id`, run `spotify-api devices` and use only an ID from that response. If the response is empty or omits a previously named device, do not reuse an older ID; ask the user to choose an available device.
6. Every response referencing existing Spotify content must include a Spotify deep link. Use `spotify_url`, or construct `https://open.spotify.com/{type}/{id}` from `spotify_uri`. A Save to Spotify deletion confirmation is the exception: the resource no longer exists, so name the deleted title without exposing its internal ID or constructing a dead link.
7. Reference Spotify by name ("on Spotify" / "via Spotify") whenever you surface content or confirm an action.
8. Flag explicit content: when `is_explicit: true`, show `[E]` next to the title.
9. After a direct `spotify-api` playback change (`play`, `skip`, `previous`, `resume`), follow up with `now-playing` and name the track plus creator; never confirm with only a device name. Exception: for new playback during a voice call, follow **Voice playback** instead.
10. A successful playback response means the action took effect. If playback still errors after CLI retries, surface it once in plain user-facing language. If an action is not available, point the user to the Spotify app rather than speculating.
11. If an exact song or album by an artist is missing from search, or a known Spotify item cannot be resolved for playlist or playback actions, do not substitute a cover, tribute, karaoke, or similarly named item. Relay `catalog_fallback.message` verbatim; it already renders the approved Muse copy with Markdown links to the requested content search and the exact artist page. Do not add a cause, preamble, follow-up, or alternative wording; blame the user's account; suggest reconnecting; or claim the item was removed from Spotify.