OAuth (PKCE)
🎧 Spotify
Search the catalog, manage playlists and your library, and control playback.
What you can do
- Search the catalog, and look up albums, artists, shows and audiobooks
- Create playlists and add or remove tracks
- Save and follow items in your library, and search it
- See your recently played tracks, and your top tracks and artists
- Control playback on an active device (needs Spotify Premium)
Setup
Create your own app in the Spotify Developer Dashboard, with the Web API and the redirect URI http://127.0.0.1:3010/callback. Copy its Client ID, then run:
agentio spotify profile add --client-id <id>
No client secret is needed. Add --read-only to request read access only, or --no-browser to paste the redirect URL back over SSH.
Good to know
- Spotify ends a sign-in 6 months after it started.
agentio statuswarns when fewer than 14 days remain; sign in again withagentio profile reauth spotify. - An app in Development Mode serves at most 5 people, each added in the dashboard.
- Spotify's terms forbid using its content to train AI models.
Command reference
-
agentio spotify accountShow the connected Spotify account
--profile <name>--json--uris-only -
agentio spotify search <query>Search the Spotify catalog
--limit <n>--offset <n>--all--json--uris-only--profile <name>--type <types>--market <CC> -
agentio spotify get <uri-or-url>Look up a catalog item by URI, URL, or ID
--type <type>--profile <name>--json--uris-only -
agentio spotify album tracks <album>List an album's tracks
--limit <n>--offset <n>--all--json--uris-only--profile <name> -
agentio spotify artist albums <artist>List an artist's albums
--include <groups>--limit <n>--offset <n>--all--json--uris-only--profile <name> -
agentio spotify show episodes <show>List a show's episodes
--limit <n>--offset <n>--all--json--uris-only--profile <name> -
agentio spotify audiobook chapters <audiobook>List an audiobook's chapters
--limit <n>--offset <n>--all--json--uris-only--profile <name> -
agentio spotify playlist listList the user's playlists
--owned--collaborative--limit <n>--offset <n>--all--json--uris-only--profile <name> -
agentio spotify playlist find <text>Find playlists by name or description (fetches all pages; may use many requests)
--json--uris-only--profile <name> -
agentio spotify playlist get <playlist>Show playlist details (without items)
--json--uris-only--profile <name> -
agentio spotify playlist items <playlist>List playlist items (owned/collaborative only)
--limit <n>--offset <n>--all--json--uris-only--profile <name> -
agentio spotify playlist create <name>Create a playlist (private by default)
--description <text>--public--collaborative--profile <name> -
agentio spotify playlist update <playlist>Update playlist details
--name <name>--description <text>--public--private--collaborative--no-collaborative--profile <name> -
agentio spotify playlist add <playlist> <items...>Add tracks/episodes to a playlist
--position <n>--skip-duplicates--profile <name> -
agentio spotify playlist remove <playlist> <items...>Remove tracks/episodes from a playlist
--snapshot <id>--profile <name> -
agentio spotify playlist reorder <playlist>Reorder playlist items (1-based positions)
--from <index>--to <index>--count <n>--snapshot <id>--profile <name> -
agentio spotify playlist replace <playlist> <items...>Replace all playlist items
--yes--profile <name> -
agentio spotify playlist dedupe <playlist>Remove duplicate URIs, keeping the first copy
--dry-run--profile <name> -
agentio spotify playlist cover <playlist>Get or set the playlist cover image
--set <file.jpg>--output <file>--profile <name> -
agentio spotify playlist delete <playlist>Unfollow a playlist (Spotify has no real delete)
--yes--profile <name> -
agentio spotify playlist export <playlist>Export playlist items
--format <fmt>--profile <name> -
agentio spotify library listList saved/followed items
--type <type>--limit <n>--offset <n>--all--json--uris-only--profile <name> -
agentio spotify library search <text>Search your library (fetches all matching types each run; may use many requests)
--type <types>--in-playlists--json--uris-only--profile <name> -
agentio spotify library save <items...>Save/follow items (batches of 40)
--profile <name> -
agentio spotify library remove <items...>Remove/unfollow items (batches of 40)
--profile <name> -
agentio spotify library contains <items...>Check whether items are saved/followed
--profile <name> -
agentio spotify historyRecently played (API returns at most the last 50 plays)
--limit <n>--after <time>--before <time>--json--uris-only--profile <name> -
agentio spotify top tracksTop tracks for a time range
--range <range>--limit <n>--offset <n>--all--json--uris-only--profile <name> -
agentio spotify top artistsTop artists for a time range
--range <range>--limit <n>--offset <n>--all--json--uris-only--profile <name> -
agentio spotify player statusCurrent playback state
--json--uris-only--profile <name> -
agentio spotify player devicesList available devices
--json--uris-only--profile <name> -
agentio spotify player play [items...]Resume or start playback
--context <uri>--offset <n-or-uri>--position <m:ss|ms>--device <name-or-id>--profile <name> -
agentio spotify player pausePause playback
--device <name-or-id>--profile <name> -
agentio spotify player nextSkip to next
--device <name-or-id>--profile <name> -
agentio spotify player previousSkip to previous
--device <name-or-id>--profile <name> -
agentio spotify player seek <position>Seek to a position
--device <name-or-id>--profile <name> -
agentio spotify player volume <percent>Set volume 0-100
--device <name-or-id>--profile <name> -
agentio spotify player shuffle <state>Set shuffle on/off
--device <name-or-id>--profile <name> -
agentio spotify player repeat <state>Set repeat mode
--device <name-or-id>--profile <name> -
agentio spotify player queueShow the playback queue
--json--uris-only--profile <name> -
agentio spotify player queue add <items...>Add items to the queue (one API call each)
--device <name-or-id>--profile <name> -
agentio spotify player transfer <device>Transfer playback to a device
--play--profile <name>