COMMAND REFERENCE

Command Reference

Control Spotify playback, manage your library, search the catalog, and build automations — all from the command line. Every command returns structured JSON.

$ spotify <command> [options]

Authentication 3 commands

Manage OAuth tokens and session state. All auth data is stored locally — nothing is sent to third-party servers.

Authenticate with Spotify using OAuth 2.0 PKCE. Opens browser to authorize, then stores tokens locally.

$ spotify login [--client-id <id>]

Option	Type	Description
`--client-id`	`string`	Use a custom Spotify app client ID

OUTPUT

json

{ "status": "logged_in", "expires_at": 1700000000, "scope": "user-read-playback-state ..." }

logout AUTH

Clear stored OAuth tokens from disk.

$ spotify logout

OUTPUT

json

{ "status": "logged_out" }

auth status AUTH

Show current token validity and granted OAuth scopes.

$ spotify auth status

OUTPUT

json

{ "status": "valid", "expires_at": 1700000000, "scope": ["user-read-playback-state", "user-modify-playback-state", "..."] }

Player 14 commands

Control playback, manage the queue, and interact with Spotify Connect devices. Most commands accept an optional --device flag to target a specific device.

now PLAYER

Get the currently playing track with playback state.

$ spotify now

json

{
  "item": {
    "name": "Bohemian Rhapsody",
    "artists": [{ "name": "Queen" }],
    "album": { "name": "A Night at the Opera" }
  },
  "is_playing": true,
  "progress_ms": 42000
}

play PLAYER

Start or resume playback with optional targeting.

$ spotify play [--uri <uri>] [--context <uri>] [--device <id>] [--offset <n>] [--position <ms>]

Option	Type	Description
`--uri`	`string`	Spotify URI of a track to play
`--context`	`string`	Context URI (album, playlist, artist)
`--device`	`string`	Target device ID
`--offset`	`integer`	Zero-based track offset within context
`--position`	`integer`	Start position in milliseconds

pause PLAYER

Pause playback on the active device.

$ spotify pause [--device <id>]

next PLAYER

Skip to the next track in the queue.

$ spotify next [--device <id>]

prev PLAYER

Skip to the previous track.

$ spotify prev [--device <id>]

seek PLAYER

Seek to a position in the current track.

$ spotify seek <ms> [--device <id>]

Option	Type	Description
`<ms>`	`integer`	Position in milliseconds (non-negative)
`--device`	`string`	Target device ID

volume PLAYER

Set playback volume (0–100).

$ spotify volume <0-100> [--device <id>]

Option	Type	Description
`<0-100>`	`integer`	Volume level (0–100)
`--device`	`string`	Target device ID

shuffle PLAYER

Toggle shuffle mode on or off.

$ spotify shuffle <on|off> [--device <id>]

repeat PLAYER

Set repeat mode: off, track, or context.

$ spotify repeat <off|track|context> [--device <id>]

queue PLAYER

Show the current playback queue.

$ spotify queue

queue add PLAYER

Add a track to the end of the playback queue.

$ spotify queue add <uri> [--device <id>]

devices PLAYER

List all available Spotify Connect devices.

$ spotify devices

transfer PLAYER

Transfer playback to a different device.

$ spotify transfer <device_id> [--play]

Option	Type	Description
`<device_id>`	`string`	Target device ID
`--play`	`boolean`	Start playback on the new device

recent PLAYER

Recently played tracks with optional cursor-based pagination.

$ spotify recent [--limit <n>] [--after <timestamp>] [--before <timestamp>]

Option	Type	Description
`--limit`	`integer`	Number of items to return
`--after`	`integer`	Unix timestamp — return items after this
`--before`	`integer`	Unix timestamp — return items before this

Search 1 command

Full-text search across the Spotify catalog. Supports tracks, albums, artists, and playlists.

search SEARCH

Search the Spotify catalog. Defaults to searching for tracks.

$ spotify search <query> [--type <type>] [--limit <n>] [--offset <n>]

Option	Type	Default	Description
`<query>`	`string`		Search query (multiple words joined)
`--type`	`string`	`track`	Comma-separated types: `track`, `album`, `artist`, `playlist`
`--limit`	`integer`		Number of results to return
`--offset`	`integer`		Result offset for pagination

$ spotify search "Miles Davis" --type artist --limit 3

json

{
  "artists": {
    "items": [
      { "name": "Miles Davis", "uri": "spotify:artist:0kbYTNQb1g4...", "popularity": 72 }
    ]
  }
}

Tracks 6 commands

Look up individual tracks, analyze audio features, get recommendations, and manage your saved library.

track TRACKS

Get detailed track metadata.

$ spotify track <id>

track features TRACKS

Get audio analysis features for a track.

$ spotify track features <id>

Deprecated

Spotify removed access to the Audio Features API for most apps in November 2024. This command may return a 403 error.

json

{
  "danceability": 0.735,
  "energy": 0.578,
  "key": 5,
  "loudness": -5.883,
  "tempo": 120.08,
  "valence": 0.624,
  "acousticness": 0.014
}

track recommendations TRACKS

Get track recommendations based on seed tracks, artists, or genres. At least one seed type is required.

$ spotify track recommendations --seed-tracks <ids> --seed-artists <ids> --seed-genres <genres> [--limit <n>]

Option	Type	Description
`--seed-tracks`	`string`	Comma-separated track IDs
`--seed-artists`	`string`	Comma-separated artist IDs
`--seed-genres`	`string`	Comma-separated genre names
`--limit`	`integer`	Number of recommendations

Deprecated

Spotify removed access to the Recommendations API for most apps in November 2024. This command may return a 403 or 404 error.

track saved TRACKS

List saved tracks in your library.

$ spotify track saved [--limit <n>] [--offset <n>]

track save TRACKS

Save one or more tracks to your library.

$ spotify track save <id...>

track remove TRACKS

Remove one or more tracks from your library.

$ spotify track remove <id...>

Albums 5 commands

Fetch album metadata, list album tracks, and manage your saved album library.

album ALBUMS

Get album details and metadata.

$ spotify album <id>

album tracks ALBUMS

List all tracks in an album.

$ spotify album tracks <id> [--limit <n>] [--offset <n>]

album saved ALBUMS

List saved albums in your library.

$ spotify album saved [--limit <n>] [--offset <n>]

album save ALBUMS

Save one or more albums to your library.

$ spotify album save <id...>

album remove ALBUMS

Remove one or more albums from your library.

$ spotify album remove <id...>

Playlists 6 commands

Create, modify, and browse playlists. Supports adding and removing tracks by URI, name match, or index position.

playlist PLAYLISTS

Get playlist details and metadata.

$ spotify playlist <id>

playlist list PLAYLISTS

List your playlists.

$ spotify playlist list [--limit <n>] [--offset <n>]

playlist tracks PLAYLISTS

List tracks in a playlist.

$ spotify playlist tracks <id> [--limit <n>] [--offset <n>]

playlist add PLAYLISTS

Add tracks to a playlist at an optional position.

$ spotify playlist add <playlist_id> <uri...> [--position <n>]

Option	Type	Description
`<playlist_id>`	`string`	Target playlist ID
`<uri...>`	`string`	One or more Spotify track URIs
`--position`	`integer`	Zero-based insert position

playlist remove PLAYLISTS

Remove tracks from a playlist by URI, name match, or index.

$ spotify playlist remove <playlist_id> [uri...] [--match <name>] [--index <n>]

Option	Type	Description
`<playlist_id>`	`string`	Target playlist ID
`[uri...]`	`string`	Track URIs to remove
`--match`	`string`	Remove tracks matching name or artist name (repeatable)
`--index`	`string`	Remove tracks at 1-based positions (comma-separated, repeatable)

At least one of uri, --match, or --index is required.

# Remove by name match
$ spotify playlist remove 37i9dQZF1DXcBWIGoYBM5M --match "Bohemian"

# Remove by index
$ spotify playlist remove 37i9dQZF1DXcBWIGoYBM5M --index 1,3,5

playlist create PLAYLISTS

Create a new playlist.

$ spotify playlist create <name> [--description <text>] [--public]

Option	Type	Description
`<name>`	`string`	Playlist name
`--description`	`string`	Playlist description
`--public`	`boolean`	Make the playlist public

User 5 commands

View your profile, top listening stats, and manage artist follows.

me USER

Get the current user's profile.

$ spotify me

top USER

Your top artists or tracks over different time ranges.

$ spotify top <artists|tracks> [--time-range <range>] [--limit <n>] [--offset <n>]

Option	Type	Default	Description
`<artists\|tracks>`	`string`		Item type
`--time-range`	`string`	`medium_term`	`short_term` (4 weeks), `medium_term` (6 months), `long_term` (all time)
`--limit`	`integer`		Number of items
`--offset`	`integer`		Result offset

json

{
  "items": [
    { "name": "Radiohead", "uri": "spotify:artist:4Z8W4fKeB5YxbusRsdQVPb", "popularity": 82 }
  ]
}

following USER

List followed artists.

$ spotify following [--limit <n>] [--after <artist_id>]

Option	Type	Description
`--limit`	`integer`	Number of items
`--after`	`string`	Cursor — last artist ID from previous page

follow USER

Follow one or more artists.

$ spotify follow <id...>

unfollow USER

Unfollow one or more artists.

$ spotify unfollow <id...>

Exit Codes

All commands use consistent exit codes for scripting and automation.

Code	Name	Meaning
`0`	`SUCCESS`	Command completed successfully
`1`	`ARGS`	Invalid arguments or missing required options
`2`	`AUTH`	Not logged in or token expired
`3`	`API`	Spotify API returned an error (4xx/5xx)
`4`	`NETWORK`	Network connectivity failure

Errors are written to stderr as JSON:

json

{ "error": "No active device found", "details": { "status": 404 } }

Command Reference ​

Authentication 3 commands ​

login AUTH ​

logout AUTH ​

auth status AUTH ​

Player 14 commands ​

now PLAYER ​

play PLAYER ​

pause PLAYER ​

next PLAYER ​

prev PLAYER ​

seek PLAYER ​

volume PLAYER ​

shuffle PLAYER ​

repeat PLAYER ​

queue PLAYER ​

queue add PLAYER ​

devices PLAYER ​

transfer PLAYER ​

recent PLAYER ​

Search 1 command ​

search SEARCH ​

Tracks 6 commands ​

track TRACKS ​

track features TRACKS ​

track recommendations TRACKS ​

track saved TRACKS ​

track save TRACKS ​

track remove TRACKS ​

Albums 5 commands ​

album ALBUMS ​

album tracks ALBUMS ​

album saved ALBUMS ​

album save ALBUMS ​

album remove ALBUMS ​

Playlists 6 commands ​

playlist PLAYLISTS ​

playlist list PLAYLISTS ​

playlist tracks PLAYLISTS ​

playlist add PLAYLISTS ​

playlist remove PLAYLISTS ​

playlist create PLAYLISTS ​

User 5 commands ​

me USER ​

top USER ​

following USER ​

follow USER ​

unfollow USER ​

Exit Codes ​

Command Reference

Authentication 3 commands

login AUTH

logout AUTH

auth status AUTH

Player 14 commands

now PLAYER

play PLAYER

pause PLAYER

next PLAYER

prev PLAYER

seek PLAYER

volume PLAYER

shuffle PLAYER

repeat PLAYER

queue PLAYER

queue add PLAYER

devices PLAYER

transfer PLAYER

recent PLAYER

Search 1 command

search SEARCH

Tracks 6 commands

track TRACKS

track features TRACKS

track recommendations TRACKS

track saved TRACKS

track save TRACKS

track remove TRACKS

Albums 5 commands

album ALBUMS

album tracks ALBUMS

album saved ALBUMS

album save ALBUMS

album remove ALBUMS

Playlists 6 commands

playlist PLAYLISTS

playlist list PLAYLISTS

playlist tracks PLAYLISTS

playlist add PLAYLISTS

playlist remove PLAYLISTS

playlist create PLAYLISTS

User 5 commands

me USER

top USER

following USER

follow USER

unfollow USER

Exit Codes