Skip to content
spotuify

Your music keeps playing after you quit.

spotuify is a Spotify daemon for the terminal: a keyboard-native TUI, a pipeable CLI, an MCP server for agents, and a macOS menubar app, all on one process that owns playback.
Install Quick start What you can do

Homebrew

Terminal window
brew tap planetaryescape/spotuify
brew trust --formula planetaryescape/spotuify/spotuify
brew install planetaryescape/spotuify/spotuify

Linux x86_64

Terminal window
curl -fsSLO https://raw.githubusercontent.com/planetaryescape/spotuify/main/install.sh
bash install.sh

Windows x64

Terminal window
$Version = "v<version>"
$Archive = "spotuify-$Version-windows-x86_64.zip"
Invoke-WebRequest "https://github.com/planetaryescape/spotuify/releases/download/$Version/$Archive" -OutFile $Archive
Expand-Archive $Archive -DestinationPath "$env:LOCALAPPDATA\spotuify\bin" -Force

Checksums, Windows download URL, and other install methods

1 daemon
4 clients
57 commands
5 output formats
37 mcp tools
10 tui screens

spotuify is for the part of your day where Spotify should behave like the rest of your tools. Open the TUI when you want to browse. Use commands when you already know the action. The one-command version is still there:

Terminal window
spotuify play "burial archangel"

What spotuify does

Section titled “What spotuify does”
  • Playback that outlives the client. The daemon embeds librespot and is the Spotify Connect device, so closing any client never stops the audio.
  • Pipeable everywhere. 57 commands with table, json, jsonl, csv, or ids output, built for fzf, jq, and xargs.
  • Local cache and search. SQLite plus a Tantivy index over your library, playlists, and history, so search and analytics answer from disk.
  • Preview and undo writes. Playlist and library mutations show a dry-run first and land in a reversible op log.
  • Built for agents. An MCP server with 37 tools, backed by the same daemon that plays the audio.
  • A real TUI. Ten screens with album art, a live spectrum, synced lyrics, and vim-style keys.
  • Listening analytics on disk. Top artists, habits, and rediscovery, derived locally without hitting the Spotify API.
  • macOS menubar app. A native SwiftUI client on the same socket, one client among four.

One daemon, four clients

Section titled “One daemon, four clients”

The daemon embeds librespot and registers as the Spotify Connect device, so it is not remote-controlling some other player: it is the player. It also keeps a metadata cache and a local search index. Everything else is a view over one Unix socket.

tui, the flagship

Ten screens: player, search, library, playlists, queue, history, devices, lyrics, diagnostics, notifications. Album art and a live spectrum rendered in the terminal. Synced lyrics. Vim-style keys. Quitting it changes nothing about the music.

Terminal window
spotuify

cli, the contract

If the TUI can do it, spotuify <command> can do it: 57 commands, output as table, json, jsonl, csv, or ids. fzf, jq, xargs, and your status bar are part of the product.

Terminal window
spotuify search "luther vandross" --type track --format ids \
  | fzf \
  | xargs spotuify play-uri

agents

Tell your agent what you are in the mood for. It runs the same CLI you do: plan candidates, resolve tracks, preview the playlist, create it once you approve. Prefer a server? The built-in MCP server exposes 37 tools, backed by the daemon that plays the audio.

Terminal window
spotuify mcp

macos menubar

A native SwiftUI player and menubar app on the same socket, for the moments you want a window instead of a terminal. One client among four, not the product.

Download the DMG

The contract

Section titled “The contract”

Forty seconds of the whole claim, on tape: play from the shell, browse in the TUI, quit it, prove playback from a pipe, then queue five tracks through stdin.

the music outlives the client

Playback, queue, devices, and cache live in the daemon. Close the TUI mid-song; nothing skips. Reattach from any client and the state is where you left it.

Terminal window
spotuify status --format json

metadata on disk, music streamed

The local store is metadata only: SQLite rows and a Tantivy index over your library, playlists, and listening history. Search and analytics answer from disk. The audio itself streams from Spotify, same as any Connect device.

Terminal window
spotuify search "ambient" --source local --format jsonl
spotuify analytics top --kind artists --since 30d

preview writes, then commit

Playlist writes can show the exact change before touching Spotify, and playlist and library writes land in an operation log you can reverse. Useful when a script or agent made the list.

Terminal window
spotuify playlist create "Exile" --from candidates.jsonl --dry-run
spotuify playlist create "Exile" --from candidates.jsonl --yes
spotuify ops undo --dry-run
TUICLIMCPdaemonSQLiteTantivySpotify

The bet

Section titled “The bet”

Backfill local analytics from Last.fm:

Terminal window
spotuify analytics import lastfm --user your-lastfm-user --from 2024-01-01 --format json
spotuify analytics import lastfm --user your-lastfm-user --from 2024-01-01 --apply --format json

Why not just another TUI

Section titled “Why not just another TUI”

Plenty of Spotify terminal apps are built around the screen. spotuify is built around the command surface. If an action matters in the TUI, it should be reachable from spotuify <command> too.

That costs more command plumbing, but it gives us something concrete to test, script, and hand to agents. The screen is optional. The daemon and CLI are the contract.

Pick your path

Section titled “Pick your path”

Status

Section titled “Status”

Active and dogfooded daily: real and usable, released often, not finished. Expect the occasional rough edge while the player and sync settle. See what’s planned in the Implementation Roadmap and what shipped in the releases.