gregoryg/aipihkal/spotify-cli

Spotify CLI

Use spotify-cli as the account-level Spotify control surface. Prefer compact JSON and the fewest commands that safely answer or perform the request.

Locate the tool

Check before planning a command sequence:

1. command -v spotify-cli
2. a user-provided checkout's .venv/bin/spotify-cli or venv/bin/spotify-cli
3. python -m spotify_cli when that module is already available

If none exists, state exactly what was checked. Do not invent playback, search, or library results. Only discuss installation when the user asks for setup help.

Default invocation

Use compact JSON for agent work:

spotify-cli --compact COMMAND

Fast paths: playback requests

Assume spotify-cli is installed, authenticated and available on PATH.

For ordinary playback actions, execute the known command directly. Do not call --help, devices list, playback current, or search separately unless the request is ambiguous or the command fails.

Known device aliases

Direct patterns

Play an artist on a named device:

spotify-cli --compact search-and-play --type artist \
  --device-id DEVICE_ID "ARTIST"

Move current playback to a named device and keep it playing:

spotify-cli --compact devices transfer DEVICE_ID --play

For these patterns, use the device ID from the alias table directly. Fall back to devices list only when the requested name is absent from the table or transfer fails.

For a documented fast path, run it directly. Inspect =spotify-cli COMMAND --help= only when the needed syntax is not documented, an option is uncertain, or the direct command fails.

Choose the shortest path

Authentication

Start diagnosis with:

spotify-cli doctor
spotify-cli auth status

Normal login is spotify-cli auth login. If an older cached token lacks scopes introduced by a CLI upgrade, use:

spotify-cli auth login --force

The durable config is normally ${XDG_CONFIG_HOME:-~/.config}/spotify-cli/spotify-cli.conf. Useful helpers are:

spotify-cli config init --client-id "your-client-id"
spotify-cli config show

Read references/headless-auth.md only for remote/headless login.

Playback and search

Direct transport actions need no read-before-write preflight:

spotify-cli --compact playback current
spotify-cli --compact playback pause
spotify-cli --compact playback play
spotify-cli --compact playback next
spotify-cli --compact playback volume 50

Prefer search-and-play for a straightforward request:

spotify-cli --compact search-and-play "take five"
spotify-cli --compact search-and-play --type artist "Lyle Lovett"
spotify-cli --compact search-and-play --type album "The Road to Ensenada"
spotify-cli --compact search-and-play --type playlist "Bossa Nova"

Use --dry-run or explicit search when title ambiguity matters:

spotify-cli --compact search-and-play "take five" --dry-run
spotify-cli --compact search "kind of blue" --type track --limit 5
spotify-cli --compact playback play --uri spotify:track:...

For an album, playlist, or artist context:

spotify-cli --compact playback play --context-uri spotify:album:...

For an episode or one or more tracks, repeat --uri as needed:

spotify-cli --compact playback play --uri spotify:episode:...

Devices and queue

When starting new content on a named device, resolve its ID and pass it directly to the playback command. Do not transfer playback first:

spotify-cli --compact devices list
spotify-cli --compact search-and-play --type playlist --device-id DEVICE_ID "Bossa Nova"
spotify-cli --compact playback play --device-id DEVICE_ID --context-uri spotify:playlist:...

Use devices transfer when moving existing playback without selecting new content:

spotify-cli --compact devices transfer DEVICE_ID --play
spotify-cli --compact queue get
spotify-cli --compact queue add spotify:track:...

Playback mutations generally require Premium and an active Spotify Connect device. If no device is active, ask the user to open Spotify somewhere or transfer to a device returned by devices list.

Playlists and library

Resolve exact item and playlist identifiers before mutation:

spotify-cli --compact playlists list --limit 50
spotify-cli --compact playlists add-items PLAYLIST_ID spotify:track:...
spotify-cli --compact playlists remove-items PLAYLIST_ID spotify:track:...

Saved items use the library family:

spotify-cli --compact library tracks save spotify:track:...
spotify-cli --compact library albums remove spotify:album:...
spotify-cli --compact library shows save spotify:show:...
spotify-cli --compact library episodes save spotify:episode:...

Artist following is separate from saved-library items:

spotify-cli --compact artists list-followed --limit 10
spotify-cli --compact artists follow spotify:artist:...
spotify-cli --compact artists unfollow spotify:artist:...

Podcasts

Spotify models podcasts as shows containing episodes:

spotify-cli --compact search "No Hay Tos" --type show --limit 5
spotify-cli --compact shows get spotify:show:...
spotify-cli --compact shows episodes spotify:show:... --limit 10
spotify-cli --compact episodes get spotify:episode:...

Use the first returned episode as the latest visible result only after confirming the response order. Account visibility can include private or linked feeds.

The CLI can expose Spotify state, but it is not a durable listening journal or want-to-listen tracker. Do not invent local tracking files or schemas as part of this skill; that belongs to a separate user-owned application.

Discovery and curation

For mood-based discovery or playlist construction, read references/curation-patterns.md. Search results are candidates, not verdicts: form a thesis, choose anchors, widen carefully, sequence coherently, then iterate.

Failure handling

Read references/failure-modes.md when a command fails. Key rules:

• Empty playback current output can validly mean nothing is playing.
• Do not retry mutations blindly after an ambiguous network/API failure; inspect

state first to avoid duplicate playlist or queue changes.

• Smart Shuffle cannot reliably be restored through the current Web API after a

shuffle mutation.

• Reauthorize with auth login --force after adding scopes to an existing setup.
• Spotify's removed recommendations endpoints are not a usable fallback for

discovery.

Prefer Spotify URIs from command output. The CLI also accepts supported Spotify URLs and bare IDs, but URIs preserve the item type explicitly.