https://github.com/crafter-station/spoti-cli
Spotify Web API from your terminal. Search, recommend, create playlists. Built for AI agents.
https://github.com/crafter-station/spoti-cli
ai-agents bun cli music playlist spotify typescript
Last synced: 3 months ago
JSON representation
Spotify Web API from your terminal. Search, recommend, create playlists. Built for AI agents.
- Host: GitHub
- URL: https://github.com/crafter-station/spoti-cli
- Owner: crafter-station
- Created: 2026-03-24T07:16:00.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T08:13:45.000Z (4 months ago)
- Last Synced: 2026-03-25T09:02:47.000Z (4 months ago)
- Topics: ai-agents, bun, cli, music, playlist, spotify, typescript
- Language: TypeScript
- Homepage: https://spoti-cli.crafter.run
- Size: 104 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# spoti-cli
Spotify Web API from your terminal. Playback control, personalization, library management, and playlists. Built for AI agents.
## Install
```bash
bun add -g @crafter/spoti-cli
```
## Setup
1. Create a Spotify app at [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard/create)
- Set redirect URI to `http://127.0.0.1:8888/callback`
- Check **Web API**
2. Authenticate:
```bash
spoti-cli auth --client-id YOUR_CLIENT_ID
```
For playback, library, and personalization commands:
```bash
spoti-cli auth --upgrade
```
## Commands
### Playback Control
```bash
spoti-cli player now --json # What's playing
spoti-cli player play --uri spotify:track:ID # Play a track
spoti-cli player pause # Pause
spoti-cli player next # Skip
spoti-cli player prev # Previous
spoti-cli player queue spotify:track:ID # Add to queue
spoti-cli player devices --json # List devices
spoti-cli player volume 75 # Set volume
spoti-cli player shuffle on # Toggle shuffle
spoti-cli player repeat track # Set repeat mode
```
### Search & Discovery
```bash
spoti-cli search "Daft Punk" --type artist --json
spoti-cli search "Around the World" --type track --limit 5
spoti-cli recommend --seed-genres electronic --energy 0.8 --limit 20 --json
```
### Personalization
```bash
spoti-cli top tracks --range short_term --limit 10 --json # Last 4 weeks
spoti-cli top artists --range medium_term --limit 10 --json # Last 6 months
spoti-cli history --limit 20 --json # Recently played
```
### Library
```bash
spoti-cli library list --limit 20 --json
spoti-cli library save --tracks ID1,ID2
spoti-cli library remove --tracks ID1,ID2
spoti-cli library check --tracks ID1,ID2 --json
```
### Track & Artist Info
```bash
spoti-cli track get ID --json
spoti-cli artist get ID --json
spoti-cli artist top-tracks ID --market US --json
spoti-cli artist albums ID --limit 10 --json
```
### Playlists
```bash
spoti-cli create "Late Night" --tracks URI1,URI2 --public --json
spoti-cli playlist list --json
spoti-cli playlist get ID --json
spoti-cli playlist add ID --tracks URI1,URI2
```
### Account
```bash
spoti-cli me --json
```
## Tunable Attributes
Fine-tune recommendations with audio features:
| Flag | Range | What it controls |
|------|-------|-----------------|
| `--energy` | 0.0-1.0 | Intensity |
| `--danceability` | 0.0-1.0 | Groove factor |
| `--valence` | 0.0-1.0 | Happy to sad |
| `--tempo` | BPM | Speed |
| `--acousticness` | 0.0-1.0 | Acoustic to electronic |
| `--instrumentalness` | 0.0-1.0 | Instrumental to vocal |
| `--popularity` | 0-100 | Mainstream factor |
## Real World Use Cases
### Voice-Controlled DJ
Build a voice-controlled Spotify DJ with real-time STT and AI intent parsing. spoti-cli handles all Spotify operations while the voice layer handles transcription and responses.
```
"Play Soda Stereo" -> search -> play (1.5s)
"Pause" -> pause (0.7s)
"Move to TV" -> transfer (0.5s)
```
### AI Playlist Curation
Analyze listening patterns and generate playlists from natural language:
```bash
spoti-cli top artists --range short_term --json # Taste profile
spoti-cli history --limit 50 --json # Filter out recent
spoti-cli artist top-tracks ARTIST_ID --json # Deep cuts
spoti-cli create "Deep Cuts" --tracks URI1,... --json
```
### Smart Auto-Queue
Queue tracks based on current vibe without interrupting playback:
```bash
spoti-cli player now --json # Current context
spoti-cli top artists --range short_term --json # Taste seeds
spoti-cli search "artist" --type track --limit 20 --json
spoti-cli player queue spotify:track:ID # Add to queue
```
### Multi-Device Control
Move playback between devices seamlessly:
```bash
spoti-cli player devices --json
spoti-cli player play --device DEVICE_ID
spoti-cli player volume 30
```
## AI Agents
Every command supports `--json`. Pair with Claude, GPT, or any LLM for natural language music control.
Install the Claude skill:
```bash
npx skills add crafter-station/skills --skill spoti-cli
```
## Stack
Bun, TypeScript, Spotify Web API, OAuth2 PKCE
## License
MIT -- [Crafter Station](https://github.com/crafter-station)