Control Spotify from the command line with the Spotify Web API and Spotify Connect.
Made for people and for AI agents.
$ spot --help
Usage: spot [options] [command]
Control Spotify from the command line
Commands:
guide Print the short manual for agents
config Manage local CLI config
auth Spotify login helpers
me Show the current Spotify account
play [options] [target...] Find something by name and play it, in one step
now Show what plays now, in a small form
search [options] <query> Search Spotify and print URIs you can reuse in
other commands
resolve [options] [songs...] Change many song names into Spotify URIs in one
step
recent [options] Show recently played tracks
taste [options] Show what you like: top artists, top songs,
recent and saved songs
devices Inspect Spotify Connect devices
playback Control Spotify playback
playlist Make and change playlists
dj Run a DJ set: a list of songs that plays in
order and can change direction
library Save or inspect library itemsSpotify CLI controls the Spotify app running on your phone, desktop, or speaker. It does not play audio inside the terminal. It is for people who live in a terminal and want to pause, skip, search or queue a track without reaching for the mouse. It is also for AI agents: an agent can play music by name, run a DJ set, and make playlists, with one command for each job.
It uses Spotify's official Web API with the PKCE login flow, so you never handle a client secret. Tokens stay in a file on your machine. The command is called spot.
- Play by name.
spot play "fear nf"finds the song and plays it. No URI necessary. - DJ sets.
spot dj startplays a list of songs in order.spot dj statusshows what was skipped.spot dj steerchanges the songs that come next. - Playlists from song names.
spot playlist create "Road trip" --from songs.txtmakes a playlist in one step and reports the songs that Spotify does not have. - Taste memory. A background watcher records each song you play and each skip.
spot feelkeeps your loves and bans, and bans are enforced.spot taste profilegives an agent all of it before a set, andspot taste scoreshows if the agent's songs get fewer skips over time. - Made for agents. One JSON object for each command, error codes with a next step, and a short manual (
spot guide). - Spotify PKCE login. No client secret, and a secure redirect finishes the flow.
- Device control. List your Spotify Connect devices and transfer playback between them.
- Full playback control. Play, pause, skip, seek, shuffle, repeat, and set volume.
- Queue, history and library. View the queue, add tracks, show recent tracks, save and remove items.
- Node.js 20+
- npm
- A Spotify Premium account for playback control
- A Spotify developer app with a client ID
git clone https://github.com/tszaks/spotify-cli.git
cd spotify-cli
npm install
npm run build
npm link
spot --helpThat gives you a global spot command. The package is not published to npm.
- Go to
https://developer.spotify.com/dashboard - Create a new app
- Set the redirect URI to:
https://szakacsmedia.com/spotify-cli/callback
- Select
Web API - Save the app
- Copy the app's
Client ID
You do not need a client secret for this CLI.
spot config set-client-id YOUR_CLIENT_ID
spot config showIf you want to override the default redirect URI:
spot config set-redirect-uri https://szakacsmedia.com/spotify-cli/callbackYou can also use environment variables:
export SPOTIFY_CLIENT_ID=YOUR_CLIENT_ID
export SPOTIFY_REDIRECT_URI=https://szakacsmedia.com/spotify-cli/callbackStart the login flow:
spot auth loginSpotify will send you to a browser. After you approve access, it will redirect to:
https://szakacsmedia.com/spotify-cli/callback?code=...
Copy that full final URL and finish the login:
spot auth finish 'PASTE_THE_FULL_CALLBACK_URL_HERE'
spot auth statusspot play "fear nf"
spot now
spot play "discovery daft punk" --type album
spot play "daft punk" --type artist
spot play "nf the search" --queue
spot playback pauseGive the agent a shell and this one line: "Run spot guide to learn how to control Spotify."
spot guide prints skills/spot/SKILL.md. To install it as a skill, copy or link the skills/spot folder into the skills folder of your agent.
When no terminal is attached, each command prints one JSON object on one line. In a terminal, it prints text. --json and --text force a mode, and so does SPOT_OUTPUT=json or SPOT_OUTPUT=text.
$ spot play "fear nf" | cat
{"ok":true,"action":"playing","item":{"uri":"spotify:track:3HfKlhohNNTLIv2t9uvmzz","type":"track","label":"FEAR - NF"},"device":{"id":"...","name":"iPhone","type":"Smartphone","active":true,"volume":100,"restricted":false},"woke":false}An error has a code, the message from Spotify, and a hint with the next step. The exit code is not zero.
{"ok":false,"error":{"code":"NO_ACTIVE_DEVICE","message":"No device is active, and more than one device is available.","hint":"Run the command again with --device <name>.","devices":[{"name":"iPhone"},{"name":"Patio Amp"}]}}| Code | Exit code | Meaning |
|---|---|---|
BAD_INPUT |
2 | The command or a value is wrong. |
NOT_LOGGED_IN, AUTH_EXPIRED, SCOPE_MISSING |
3 | A person must run spot auth login. |
NO_ACTIVE_DEVICE, DEVICE_NOT_FOUND |
4 | No device can play. The error lists the available devices. |
NOT_FOUND |
5 | Spotify has no such item. |
RATE_LIMITED, QUOTA_EXCEEDED |
6 | Wait for retryAfterSeconds. |
PREMIUM_REQUIRED, FORBIDDEN |
7 | Spotify refused the action. |
NETWORK, SPOTIFY_ERROR |
8 | No connection, or a problem at Spotify. |
spot never guesses between two speakers. When no device is active and more than one is available, it stops and lists them. Then use --device <name>, or set a default with spot config set-default-device <name>.
When Spotify is closed on all devices, --wake opens the Spotify app on this computer (macOS only). The sound then comes from this computer.
spot play "fear nf"
spot play "random access memories" --type album
spot play "morning coffee" --type playlist
spot play "road trip" --mine # one of your own playlists, by name
spot play "nf the search" --queue # next, the current song continues
spot play # resume
spot nowA set is a list of songs that plays in order. spot keeps the set in one playlist with the name spot DJ, because the Spotify queue cannot be cleared or put in a new order.
spot dj start --name "Deep focus" --note "calm, no vocals" --from songs.txt
spot dj status # current song, played, skipped, remaining
spot dj steer "Tycho - Awake" "Bonobo - Kerala" # replaces the songs that come next
spot dj stop # pause and final reportsongs.txt has one song for each line, as Artist - Title, a Spotify URI, or a link. Use --from - to read the list from stdin.
skipped means: a song before the current song that Spotify did not record as played. Spotify records a song after 30 seconds of play.
spot playlist list
spot playlist show "Road trip"
spot playlist create "Road trip" --description "Windows down" --from songs.txt
spot playlist create "Focus" "Tycho - Awake" "Bonobo - Kerala" --play
spot playlist add "Road trip" "NF - Fear"
spot playlist replace "Road trip" --from songs.txt
spot playlist remove "Road trip" spotify:track:3HfKlhohNNTLIv2t9uvmzz
spot playlist update "Road trip" --name "Road trip 2"A new playlist is private. Add --public to change that. The playlist argument is the name of one of your playlists, an id, a URI, or a link.
spot resolve "NF - Fear" "Daft Punk - Around the World"
spot resolve --from songs.txtresolve reports a song as missed when no result has the title and the artist. This catches a wrong name and a song that is not real. Add --loose to accept weak matches.
spot tasteOne reply with your top artists, top songs, recent songs and saved songs. A part that Spotify refuses is listed in unavailable with the cause. The other parts stay correct.
Spotify forgets nothing, but it tells apps very little. spot keeps its own record, so an agent can learn your taste over time.
spot watch install # macOS: record each song you play, in the background (start at login)
spot watch status # is it running, and when did it last check?
spot feel love # you like the song that plays now
spot feel ban "Artist - Title" --why "too slow"
spot feel ban --artist "Artist - Title" # never play this artist
spot feel clear "Artist - Title" # forget the earlier word
spot taste profile # what the tool learned: notes, bans, favourites, skips, situations, score
spot taste note "No vocals when working"
spot taste score # skip rate of the agent's songs for each week
spot history import ~/Downloads/my_spotify_data # years of plays from a Spotify data download- The watcher asks Spotify what plays every 20 seconds while music plays, and every 1 to 2 minutes when nothing plays. A song that changes before its end is a skip. A song that stops (pause, app closed) is not.
- Bans apply to DJ sets and to playlists that
spotmakes.--include-bannedturns this off for one command.spot playof one song is not blocked: that is a direct request. taste-notes.mdis plain text. Edit it as you like. "Rules you said" is for your own rules.- Your Spotify data download: spotify.com, Account, Privacy, "Extended streaming history". It can take up to 30 days. Unzip it, then import the folder.
- All of this stays on your computer, in
~/.config/spotify-cli/.
spot auth login
spot auth finish 'PASTE_THE_FULL_CALLBACK_URL_HERE'
spot auth status
spot auth logoutspot devices list
spot devices transfer "MacBook Pro"
spot config set-default-device "MacBook Pro"spot playback status
spot playback play
spot playback play spotify:playlist:37i9dQZF1DXcBWIGoYBM5M
spot playback play "https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC"
spot playback pause
spot playback next
spot playback previous
spot playback volume 35
spot playback seek 60000
spot playback shuffle on
spot playback repeat contextspot playback queue
spot playback add spotify:track:4uLU6hMCjMI75M1A2tKUQC spotify:track:3HfKlhohNNTLIv2t9uvmzzspot me
spot search "daft punk"
spot recent --limit 50spot library save spotify:album:4m2880jivSbbyEGAKfITCa
spot library contains spotify:track:4uLU6hMCjMI75M1A2tKUQC
spot library remove spotify:track:4uLU6hMCjMI75M1A2tKUQCSpotify changed parts of its development-mode behavior in early 2026. The main things that matter here:
- The owner of the developer app needs Spotify Premium. If Premium stops, all requests fail. After Premium starts again, Spotify can take some hours to accept requests.
- New apps need a secure redirect URI
- Search results are limited to
10per type in development mode - Spotify gives no song recommendations to apps in development mode. The person or the agent selects the songs.
- You can read the songs of a playlist only if you own it or collaborate on it
- A login lasts 180 days. Then a person must log in again.
- After an update that adds a permission (v2.0.0 adds
user-top-readforspot taste), runspot auth loginone time
Relevant docs:
https://developer.spotify.com/documentation/web-api/tutorials/code-pkce-flowhttps://developer.spotify.com/documentation/web-api/tutorials/refreshing-tokenshttps://developer.spotify.com/documentation/web-api/tutorials/february-2026-migration-guide
Run the login flow again:
spot auth login
spot auth finish 'PASTE_THE_FULL_CALLBACK_URL_HERE'Open Spotify on your phone, desktop, or speaker first, then run:
spot devices listOr add --wake to a play command to open Spotify on this computer.
The Spotify account that owns the developer app has no active Premium plan, or the plan changed in the last hours. Wait, then try again.
The login is older than a permission that the command needs. Run the login flow again.
npm run build
npm link
hash -r~/.config/spotify-cli/config.json
~/.config/spotify-cli/tokens.json (mode 600: only you can read it)
~/.config/spotify-cli/auth-session.json
~/.config/spotify-cli/dj-session.json (the current DJ set)
~/.config/spotify-cli/listening.jsonl (one line for each song that ended)
~/.config/spotify-cli/feelings.jsonl (loves, bans)
~/.config/spotify-cli/taste-notes.md (the taste file that agents read; you can edit it)
~/.config/spotify-cli/watch-state.json, watch.lock, watch.log (the watcher)
Current release: v2.0.2
Ideas for later, not scheduled:
- mood and style labels for songs from Last.fm (Spotify no longer gives this data)
- a login that finishes by itself with a local callback address
- an MCP server mode for agents that have no shell
npm test
npm run build
node dist/index.js --helpThe tests run each command against a fake Spotify that lives in memory (test/helpers/fake-spotify.ts). They never call the real Spotify API and never read your login.
CI runs npm ci, npm run build and npm test on Node 20 and 22. A design note from the first build is in docs/plans.
Bug reports and pull requests are welcome. Please read CONTRIBUTING.md first. Security problems go through SECURITY.md. Everyone taking part follows the Code of Conduct.
Docs: agent manual · design note · AGENTS.md · changelog
MIT © 2026 Tyler Szakacs