spoti

Local-first · open source

Your music.
In your terminal.

A fast, keyboard-driven TUI and CLI for controlling Spotify through Spotify Connect. Search, play, queue, switch devices, manage playlists, browse your library, and follow synced lyrics without leaving the terminal.

Get started View on GitHub
npm install --global @bzenky/spoti

Requires Node.js 22+ and Spotify Premium for playback controls.

spoti Player playing Born and Raised - Reprise by John Mayer, with album artwork, playback progress, saved-track status, and keyboard controls
The interactive Player with album artwork and saved-track status. Press h on Player or Lyrics to like or unlike the current track. Player shows saved status below progress, with a blank row after artist/album details in larger windows. Artwork appears in supported terminals.

One tool, two modes

Built for the way terminals work

Open the interactive interface for exploration, or use focused commands in scripts and daily workflows.

Keyboard-first TUI

Player, Search, Queue, Devices, Library, Lyrics, and Help screens with responsive layouts, album artwork in supported terminals, top tracks and artists, and playlist actions. Press h on Player or Lyrics to like or unlike the current track; the heart indicator shows its saved status. Inside a playlist, press / to filter by title or artist across all pages. Matching ignores case and accents. Results appear as tracks load; use arrows and Enter to play, Ctrl+R to retry a failed load, and Esc to clear the filter and restore your place. In Devices, press o to open Spotify locally and refresh the list; press r again if Spotify needs more time to appear.

spoti interactive

Composable CLI

Control playback, inspect state, search Spotify, transfer devices, organize playlists, and manage your library one command at a time. Press Esc or Ctrl+C to cancel selection prompts without changing playback.

spoti now --short

Synced lyrics

Follow the current line and control playback directly from Lyrics in the TUI, or fetch lyrics for the playing track and search results from LRCLIB.

spoti lyrics

CLI examples

Small commands.
Full control.

Ordinary multi-word searches do not need quotes. Add --first when you want deterministic, non-interactive selection. Run spoti device to list Spotify Connect devices; the printed numbers, names, and IDs can be passed back to spoti device to switch playback. If the list is empty, open Spotify on a device or run spoti launch on this computer, then refresh the list. Use spoti top tracks|artists to browse affinity rankings; --range short|medium|long selects roughly four weeks, six months, or one year. The tt and ta shortcuts open top tracks and top artists directly.

$ spoti play Fear of the Dark
$ spoti pause
$ spoti launch
$ spoti seek +30
$ spoti restart
$ spoti volume 50
$ spoti queue "Faint" --first
$ spoti playlist-create "Road trip"
$ spoti playlist-edit "Road trip" --name "Road trip 2026"
$ spoti playlist-move "Road trip" 12 3
$ spoti top tracks --range short
$ spoti tt --range long
$ spoti ta
$ spoti add "Workout" --search "Numb" --first
$ spoti device
$ spoti device 1
$ spoti device "My Computer" --default
$ spoti open
$ spoti lyrics Numb Linkin Park
$ spoti like
$ spoti unlike
$ spoti liked --limit 10
Control playback without leaving Lyrics: Space to play/pause, n/p to change tracks, ←/→ to seek, -/+ for volume, s for shuffle, and r for repeat. Press h on Player or Lyrics to like or unlike the current track; the heart shows its saved status, the shortcut hint switches between Like and Unlike, and Liked library pages reload after a change. Press Ctrl+R to refresh playback and saved status or Enter to retry a lyrics loading error. Scroll freely; press f to resume following synchronized lines. In Search, select a track and press a to add it to a playlist.

Setup

Your app.
Your credentials.

spoti uses OAuth Authorization Code with PKCE. Your public client ID and credentials stay in your local configuration; no client secret is needed or accepted.

Open Spotify Developer Dashboard
  1. 01

    Create a Spotify app

    In the Spotify Developer Dashboard, create an application and add this exact redirect URI:

    http://127.0.0.1:43821/callback

    Use 127.0.0.1 exactly—not localhost and not a wildcard.

  2. 02

    Install spoti

    npm install --global @bzenky/spoti
  3. 03

    Save your client ID and sign in

    spoti setup
    spoti login

    Authentication opens Spotify’s authorization page in your browser. If a new feature requires permissions missing from your saved credentials, run spoti login again when prompted.

  4. 04

    Start listening

    spoti interactive

    Album artwork requires an image-capable terminal and a window of at least 64 columns by 18 rows. Cover height adapts to terminal cell dimensions, and resizing reloads and redraws artwork without interrupting playback. Kitty, Ghostty, and iTerm2 support it; Windows Terminal requires Sixel support. GNOME Terminal, macOS Terminal.app, and the legacy Windows console show text only. See the terminal compatibility table for other terminals and rendering limitations.

Good to know

Clear boundaries by design

Spotify Connect

spoti controls an existing Spotify client or Connect device. It does not stream or download audio, so an available playback device is required. Run spoti launch (alias spoti app), or press o in the TUI Devices screen, to open Spotify locally. Spotify must be installed and registered to handle spotify: links; remote devices must be opened separately. The Devices screen preselects the active device, shows defaults and unavailable devices, and can reveal device IDs for duplicate names.

Premium & quota

Spotify Premium is required for playback-control commands, and a development-mode app’s owner must have Premium. Development mode has a small user allowlist and quota may be shared across apps owned by one developer account; each user should create their own app. Longer quota waits exit with a retry time.

Lyrics & privacy

Spotify does not provide lyrics through its Web API. When lyrics are requested, spoti sends the track title, artists, album, and duration to the community-run LRCLIB service. Lookups are cached in memory during the running session and never written to disk. Player and Lyrics refresh Spotify playback every ten seconds while active, and progress updates locally every second.

Lyrics licensing

Lyrics are shown with LRCLIB attribution for personal, immediate use. LRCLIB’s software license does not grant redistribution rights to copyrighted lyrics; availability and synchronization depend on community data.

Website analytics

This website uses Google Analytics to measure anonymous usage such as page views and referral sources. Google may process technical information including your IP address and browser data under its privacy policy.

Ready when you are

Put Spotify at your fingertips.

View npm package Browse releases