spotify-web-cli

A command-line interface for the Spotify Web API, with 1:1 coverage of every non-deprecated endpoint.

Requirements

• Node.js 24+ (pinned via .nvmrc / .node-version)
• A Spotify developer application (client ID + redirect URI). See the auth docs under docs/api/auth.md.

Install

npm install -g spotify-web-cli

Or run from a checkout:

git clone <repo>
cd spotify-web-cli
nvm use        # picks Node 24 from .nvmrc
npm install
npm run build
npm link       # makes `spotify` available on your PATH

Alternatively, invoke the built binary directly without npm link:

node dist/bin/spotify.js --help

Quickstart

# Register a Spotify developer app at https://developer.spotify.com/dashboard
# and set at least the client ID:
export SPOTIFY_CLIENT_ID=<your-client-id>
export SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback

# One-time login (opens browser for Authorization Code + PKCE flow)
spotify auth login

# Verify auth + fetch your profile in one shot
spotify auth whoami

# Try a command
spotify users me
spotify albums get 4aawyAB9vmqN3uQ7FjRGTy --market US

Development

npm run dev           # run CLI via tsx
npm run lint          # eslint
npm run typecheck     # tsc --noEmit
npm run test          # vitest run
npm run test:cov      # vitest run --coverage (enforces 85% thresholds)
npm run build         # emit dist/

Documentation

• docs/usage.md — task-oriented guide. Start here. Recipes for search, playback, playlists, saved library, and troubleshooting.
• docs/commands/ — exhaustive per-command reference, mapped 1:1 to the API endpoints.
• docs/api/ — per-resource-group Spotify Web API snapshot.
• docs/architecture.md — module layout, error taxonomy, exit codes.

License

MIT — see LICENSE.