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, 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.

Full-screen when you want it. Scriptable when you don’t.

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 and direct shortcuts.

spoti interactive

Composable CLI

Control playback, inspect state, search Spotify, transfer devices, and manage your library one command at a time.

spoti now --watch

Synced lyrics

Follow the current line 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.

$ spoti play Fear of the Dark
$ spoti pause
$ spoti seek +30
$ spoti volume 50
$ spoti queue "Faint" --first
$ spoti device "My Computer"
$ spoti lyrics Numb Linkin Park
$ spoti liked --limit 10
Synchronized lines follow local playback progress. Scroll freely; press f to resume following.

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.

  4. 04

    Start listening

    spoti interactive

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.

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. Only when lyrics are requested, spoti sends the track title, artists, album, and duration to the community-run LRCLIB service. Lyrics are loaded live and not persisted locally.

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.

Ready when you are

Put Spotify at your fingertips.

View npm package Browse releases