spotify

Original：🇺🇸 English
Translated
3 scripts

Control Spotify playback via CLI. Requires Spotify Premium for playback control. USE FOR: play song, play music, play [song name], play [artist], play [album], play [playlist], pause, stop music, resume, skip, next song, previous song, what's playing, now playing, current song, volume up, volume down, set volume, shuffle on, shuffle off, repeat, queue, add to queue, list devices, transfer playback, play on [device]. DO NOT USE FOR: downloading music, editing playlists, creating playlists.

2installs
Sourcebrgrp/skills
Added on

NPX Install

npx skill4agent add brgrp/skills spotify

Tags

Translated version includes tags in frontmatter
spotify-cliplayback-controlspotify-apicli-scriptspremium-integration

SKILL.md Content

View Translation Comparison →

Spotify Control

Quick Start

bash
# Play a song (handles search, device wake, everything)
./scripts/spotify-play.sh "l'amour toujours"

# Play a playlist
./scripts/spotify-play.sh "today's top hits" --type playlist

# Pause/resume/skip
./scripts/spotify-ctl.sh pause
./scripts/spotify-ctl.sh play
./scripts/spotify-ctl.sh next

Setup

Spotify Developer Account (one-time)

  1. Go to https://developer.spotify.com/dashboard
  2. Log in with your Spotify account
  3. Click Create App → name it anything → select "Web API"
  4. Add redirect URI: 
    http://127.0.0.1:17823/callback
  5. Copy your Client ID and Client Secret
Note: Requires Spotify Premium for playback control. Free accounts can only search.

First Run

First run prompts for credentials interactively:
bash
./scripts/spotify-auth.sh login
Credentials loaded from: env vars → 
~/.spotify/credentials.json
→ interactive prompt

Helper Scripts

ScriptPurpose
spotify-play.sh <query>
Search and play (handles device wake)
spotify-ctl.sh <cmd>
Playback control (pause, play, next, prev, volume, shuffle, repeat)
spotify-auth.sh login
OAuth setup
spotify-auth.sh token
Get valid token (auto-refreshes)

spotify-play.sh

bash
# Play track (default)
./scripts/spotify-play.sh "bohemian rhapsody"

# Play playlist
./scripts/spotify-play.sh "workout" --type playlist

# Play album  
./scripts/spotify-play.sh "thriller" --type album

# Play artist
./scripts/spotify-play.sh "queen" --type artist

# Play on specific device
./scripts/spotify-play.sh "song" --device "Kitchen Echo"

# Set default device
./scripts/spotify-play.sh --set-device "Kitchen Echo"

spotify-ctl.sh

bash
./scripts/spotify-ctl.sh pause
./scripts/spotify-ctl.sh play
./scripts/spotify-ctl.sh next
./scripts/spotify-ctl.sh prev
./scripts/spotify-ctl.sh volume 50
./scripts/spotify-ctl.sh shuffle on|off
./scripts/spotify-ctl.sh repeat track|context|off
./scripts/spotify-ctl.sh devices        # list devices
./scripts/spotify-ctl.sh transfer Echo  # move playback to device
./scripts/spotify-ctl.sh now            # what's playing
./scripts/spotify-ctl.sh queue          # show queue
./scripts/spotify-ctl.sh add-queue <uri> # add to queue

Direct API Access

For advanced use, get token and call API directly:
bash
TOKEN=$(./scripts/spotify-auth.sh token)

# Search
curl -s "https://api.spotify.com/v1/search?q=despacito&type=track&limit=5" \
  -H "Authorization: Bearer $TOKEN" | jq '.tracks.items[] | {name, uri}'

# Play URI
curl -s -X PUT "https://api.spotify.com/v1/me/player/play" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uris": ["spotify:track:xxx"]}'

Common Patterns

Search and play first result

bash
./scripts/spotify-play.sh "song name"

Play on specific device

bash
./scripts/spotify-play.sh "song" --device "Echo"

Control playback

bash
./scripts/spotify-ctl.sh pause
./scripts/spotify-ctl.sh volume 30
./scripts/spotify-ctl.sh shuffle on

Error Handling

ErrorSolution
No tokenRun 
./scripts/spotify-auth.sh login
No active deviceScript auto-wakes default device, or use 
--device
403 Premium requiredPlayback needs Spotify Premium
401 UnauthorizedToken auto-refreshes; if persists, re-run login

Files

~/.config/spotify/          # or $XDG_CONFIG_HOME/spotify/
├── credentials.json        # Client ID/Secret (chmod 600)
├── tokens.json             # Access/refresh tokens (chmod 600)  
└── config.json             # Default device, preferences

API Limits (Feb 2026)

  • Search: max 10 results per request
  • Batch endpoints removed (fetch individually)
  • Normalize playlist URIs: 
    playlist_v2
    → 
    playlist