Spotify CLI
A simple command-line interface for controlling Spotify playback from a Raspberry Pi (or any Linux system).
Requirements
- Python 3
- Spotify Premium account
spotipyPython library- Spotify app open on another device (phone, computer, or web player)
Installation
1. Install dependencies
pip3 install spotipy --break-system-packages2. Create a Spotify Developer App
- Go to https://developer.spotify.com/dashboard
- Log in and click "Create App"
- Set Redirect URI to
http://127.0.0.1:8888/callback - Copy the Client ID and Client Secret
3. Create config file
mkdir -p ~/.config/spotify-cli
cat << EOF > ~/.config/spotify-cli/config
SPOTIPY_CLIENT_ID=your_client_id
SPOTIPY_CLIENT_SECRET=your_client_secret
SPOTIPY_REDIRECT_URI=http://127.0.0.1:8888/callback
EOFThe script automatically loads credentials from ~/.config/spotify-cli/config.
4. Install the script
sudo cp spotify /usr/local/bin/spotify
sudo chmod +x /usr/local/bin/spotify5. Authenticate
Run any command (e.g., spotify status). On first run, you'll get a URL to open in your browser. After authorizing, copy the redirect URL (even if the page doesn't load) and paste it when prompted.
Commands
| Command | Description |
|---|---|
spotify search <query> | Search for songs (shows top 5 results) |
spotify play <song> | Search and play a song |
spotify pause | Pause playback |
spotify resume | Resume playback |
spotify next | Skip to next track |
spotify prev | Previous track |
spotify status | Show currently playing track |
spotify devices | List available Spotify devices |
Examples
# Search for a song
spotify search "stairway to heaven"
# Play a song (tip: include artist for better results)
spotify play "stairway to heaven led zeppelin"
# Check what's playing
spotify status
# Control playback
spotify pause
spotify resume
spotify nextBest Practices (for AI agents)
When using this tool on behalf of a user:
- Always search first before playing. Use
spotify search "query"to see results. - Verify the match - confirm with the user that the search results match what they were looking for.
- Then play - once confirmed, use
spotify play "exact song name artist"with the correct title/artist from the search results.
This avoids playing the wrong song due to Spotify's fuzzy search matching.
Example workflow:
# User asks: "play voice actor u projected 2"
# Step 1: Search first
spotify search "voice actor u projected 2"
# Results show: "U Projected 2 - Voice Actor, Yarrow.co"
# Step 2: Confirm with user that this is the right song
# Step 3: Play with exact match
spotify play "U Projected 2 Voice Actor"Notes
- This CLI controls playback on an existing Spotify session. You need Spotify open on another device (phone, computer, or https://open.spotify.com).
- The CLI sends commands to that device - audio plays there, not on the Pi.
- Requires Spotify Premium for playback control.
Troubleshooting
"No active device found"
Open Spotify on your phone/computer and play something, then try again.
"No devices found"
Make sure Spotify is open on at least one device and logged into the same account.
Auth token expired
Delete ~/.cache-* files and re-authenticate.