SpotiClaw

# Install dependencies
pip install requests python-dotenv
Add to path
import sys
sys.path.insert(0, "skills/spoticlaw/scripts")
from spoticlaw import player, search, playlists, library
Search for music
results = search().query("coldplay", types=["track"], limit=10)
Play a track
player().play(uris=["spotify:track:..."])
Manage playlists
playlists().create("My Playlist")
playlists().add_items("playlist_id", ["spotify:track:..."])
Save to library
library().save(["spotify:track:..."])

Or run from the scripts directory:

cd skills/spoticlaw/scripts
python -c "from spoticlaw import player; player().play(...)"

1. Create a Spotify app at https://developer.spotify.com/dashboard 2. Get CLIENT_ID and CLIENT_SECRET 3. Add http://127.0.0.1:8888/callback as Redirect URI 4. Create .env file in your LOCAL machine:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback

5. Run authentication on your LOCAL machine:

cd skills/spoticlaw/scripts
pip install -r requirements.txt
python auth.py

6. Open the displayed URL in your browser, authorize

7. Copy the token file to your agent:

# Linux/Mac - copy to agent's skill folder
cp .spotify_cache /path/to/agent/skills/spoticlaw/.spotify_cache
Or if agent is remote, copy via scp, USB, etc.
scp .spotify_cache user@agent:/path/to/skills/spoticlaw/.spotify_cache

That's it! No token ever touches the AI. The agent just reads the file.

Token Auto-Refresh

The library automatically handles token refresh only if the agent has the same app credentials in .env:

For more on Spotify's OAuth flow, see: https://developer.spotify.com/documentation/web-api/tutorials/code-flow

Required Scopes

The auth.py script requests these scopes: