morille

A terminal-based Spotify player built with TypeScript, ink (React for the terminal), and the Spotify Web API.

Install & run

npx morille

That's it. morille ships with a default Spotify Client ID baked into the binary, so the app works out of the box — no registration required for most users.

Spotify Premium is required for playback control.

Running from source

pnpm install
pnpm build
node dist/index.js

Using your own Client ID

If you want to use your own Spotify app (for development, higher rate limits, or access to more users via extended quota mode), override the embedded default with an environment variable:

1. Go to the Spotify Developer Dashboard
2. Create a new app
3. In your app settings, add http://127.0.0.1:8888/callback as a Redirect URI
4. Copy the Client ID from your app's overview page
5. Export it before running morille:

   export SPOTIFY_CLIENT_ID=your_client_id_here
   npx morille

SPOTIFY_CLIENT_ID always takes precedence over the embedded default. To change the embedded default, edit DEFAULT_SPOTIFY_CLIENT_ID in src/config.ts and rebuild.

Debug output

morille is silent on stderr by default so the terminal UI stays clean. To see internal diagnostics (fetch traces, retry notices, auth and API errors), run with the --debug flag or set the DEBUG=1 environment variable:

npx morille --debug
# or
DEBUG=1 npx morille

Debug output is written to stderr and will visibly interfere with the ink UI — this mode is intended for development, not regular use.

Usage

• Space - toggle play/pause
• n / Right arrow - next track
• p / Left arrow - previous track
• . - seek forward 10s
• , - seek backward 10s
• Up arrow - volume up 5%
• Down arrow - volume down 5%
• s - toggle shuffle
• r - cycle repeat (off / context / track)
• l - toggle lyrics display
• d - toggle queue view (up/down to navigate, enter to select)
• / - search tracks, albums, artists, playlists (type to search, left/right to switch category, enter to select)
• b - browse your playlists (enter to view tracks, enter to play)
• q - quit

Development

pnpm install
pnpm dev          # watch mode
pnpm build        # compile
pnpm test:ts      # type-check
pnpm test:biome   # lint/format check

Roadmap

• Add track to queue
• Device selection / transfer playback
• Show recently played tracks
• Like / unlike tracks (save to library)
• Keyboard shortcuts customization