dj

A command-line Spotify controller. Check what's playing, skip tracks, search the catalog, look up albums. All output is structured JSON, built for piping into jq or feeding to AI agents.

Requires Spotify Premium for playback controls (play, pause, next, previous).

Install

go install github.com/scale-flow/dj/cmd/dj@latest

Or build from source:

git clone https://github.com/Scale-Flow/dj.git
cd dj
make build
# binary lands in bin/dj

Setup

1. Create a Spotify app at https://developer.spotify.com/dashboard
2. Run dj auth login and enter your Client ID and Secret when prompted
3. Authorize in the browser

The CLI stores tokens in your OS keychain when available, falling back to ~/.config/dj/oauth-tokens.json on headless systems.

Usage

# What's playing right now?
dj player now-playing

# Full playback state (device, shuffle, repeat)
dj player status

# Control playback
dj player play
dj player pause
dj player next
dj player previous

# List connected devices
dj player devices

# Search
dj search --q "Justice D.A.N.C.E." --type track

# Look up a track or album by ID
dj tracks get --id 33yAEqzKXexYM3WlOYtTfQ
dj albums get --id 2WT1pbYjLJciAR26yMebkH
dj albums tracks --id 2WT1pbYjLJciAR26yMebkH

Output Format

Every command writes a JSON envelope to stdout:

{"ok": true, "data": {"is_playing": true, "item": {"name": "D.A.N.C.E."}}}

Errors follow the same shape:

{"ok": false, "error": {"code": "unauthorized", "message": "token expired"}}

Human-readable messages go to stderr. Pipe stdout freely.

Global Flags

Flag	Description
--pretty	Pretty-print JSON output
--dry-run	Preview without executing
--yes	Skip confirmation prompts
--profile	Switch between named credential profiles
--base-url	Override the Spotify API base URL

Built With

Generated by marten, a code generator for agent-native CLIs.

License

MIT