spotterm

English | 日本語

A fast Spotify TUI for your terminal, built on the official Spotify Web API.

spotterm controls playback, searches, browses your library, and shows a live "Now Playing" dashboard (with album cover art in supporting terminals) — all from a single interactive TUI. It uses Authorization Code + PKCE (no client secret on your machine) and talks only to the official Web API — it never downloads audio or bundles any Spotify SDK.

Playback happens on any Spotify Connect device you already run (the official Spotify desktop or mobile app); spotterm just tells that device what to play.

Features

• Now Playing TUI (spotterm tui): live track/artist/album, progress bar, volume, and cover art.
• Playback control: play / pause / next / prev / seek / volume, right from the TUI.
• Search & play tracks.
• Browse & play your playlists, saved tracks, and saved albums.
• Device picker: list Connect devices and transfer playback.
• Save / unsave the current track to your library.

All actions live in the interactive TUI; the CLI has just two commands — login and tui.

Requirements

• Spotify Premium (required by the Web API for playback control).
• A Spotify Connect device to play on — the official Spotify app (desktop/mobile) running and logged in on the same account.
• Your own Spotify app Client ID (free; see Setup). Each user registers their own app.
• Rust toolchain (to build from source) — Rust 1.85+ (edition 2024).
• A Nerd Font set as your terminal font. The TUI and the login output use Nerd Font glyphs for icons (track, artist, album, volume, warnings, etc.); without one they render as tofu (□).
• For real album art: a terminal that supports an image protocol (iTerm2, kitty, WezTerm, Ghostty). Other terminals fall back to colored half-blocks automatically.

Install

Prebuilt binaries

Download a tarball for your platform from the Releases page (Linux x86_64, macOS aarch64/x86_64), then extract and put spotterm on your PATH:

tar xzf spotterm-*.tar.gz
sudo mv spotterm-*/spotterm /usr/local/bin/

Build from source

cargo install --git https://github.com/kinzaru3/spotterm
# or
git clone https://github.com/kinzaru3/spotterm && cd spotterm && cargo install --path .

Setup

1. Create a Spotify app at the Spotify Developer Dashboard and copy its Client ID.
2. In the app settings, add this Redirect URI:

   http://127.0.0.1:8888/callback
   

3. Provide your Client ID via environment variable (or a .env file — see .env.example):

   export SPOTTERM_CLIENT_ID=your_client_id_here
   # optional, defaults to http://127.0.0.1:8888/callback
   # export SPOTTERM_REDIRECT_URI=http://127.0.0.1:8888/callback
   

4. Log in (opens your browser for consent; the token is cached locally):

   spotterm login
   

Why your own Client ID? Spotify's development mode limits an app to a small number of users, so each user runs spotterm with their own registered app. No client secret is needed (PKCE), and your token is stored in your OS config directory with 0600 permissions.

Usage

spotterm has just two commands:

spotterm login   # authenticate once (PKCE; opens your browser, caches the token)
spotterm tui     # launch the interactive Now Playing dashboard

Everything — playback, search, library browsing, device switching — happens inside the TUI.

Interactive TUI

spotterm tui

Album cover art

The TUI renders album art using the best protocol your terminal supports (kitty, iTerm2, Sixel), and falls back to colored half-blocks elsewhere — so you always see something.

Inside tmux, image protocols are stripped unless passthrough is enabled. Add this to your tmux config to see real images:

set -g allow-passthrough on

Notes

• Personal, non-commercial use. spotterm is a client of the public Spotify Web API; it does not redistribute any Spotify SDK, content, or client secret.
• Cover art and track metadata are shown together, per Spotify's developer guidelines.

License

MIT © kinzaru3

This project is not affiliated with or endorsed by Spotify. "Spotify" is a trademark of Spotify AB.