Table of Contents
About
spotatui is a music player for the terminal, with a desktop app in preview. Spotify is optional: it is one of seven sources.
- Synced lyrics, and a real-time audio visualizer.
- A play queue that mixes tracks from different sources.
- Playlist sync: mirror one playlist onto Spotify, Qobuz, Subsonic or YouTube.
- Lua plugins for commands, keys, popups and themes.
- An AI DJ inside the app, or your coding agent as the DJ over MCP.
- A local listening history with stats and a shareable recap.
- A CLI for playback, search and playlists.
Spotify needs Premium. spotatui logs in with its own built-in client, so you need no developer app and no client ID.
spotatui started as a fork of spotify-tui and has since grown its own player, sources and desktop app.
Installation
Spotify is optional: every other source works without an account.
| System | Command |
|---|
| macOS, Linux, WSL | curl -fsSL https://spotatui.com/install.sh | bash |
| Windows | irm https://spotatui.com/install.ps1 | iex or winget install spotatui |
| Arch Linux | yay -S spotatui-bin |
| With Rust | cargo install --locked spotatui |
Homebrew, Nix, Void, .deb packages and building from source are in the installation guide.
- Desktop app: download the installer for your system from the latest release. See Desktop app.
- Features per build: the prebuilt terminal binaries include every source, the MCP server and the AI DJ.
cargo install builds Spotify only unless you add the features, and the Nix flake builds Spotify only.
- Updates: the terminal app updates itself. If a package manager installed it, set
behavior.disable_auto_update: true. See Updating.
Quickstart
Run spotatui. The first launch asks which sources you want. Pick Spotify to log in: spotatui shows a code and opens Spotify's pairing page, where you confirm it.
Then:
? lists every key./ searches. Choose the Songs panel with the arrow keys, press Enter to go into it, and Enter again to play a track.d switches the source and the device.z queues a track, and Shift+Q opens the queue.spotatui --help shows the CLI.
Sources
| Source | You need |
|---|
| Spotify | A Premium account |
| Local Files | A music folder |
| Subsonic / Navidrome | A server account |
| Internet Radio | Nothing (30k+ stations from radio-browser.info) |
| YouTube | yt-dlp on your PATH |
| Qobuz | A paid Qobuz account |
| Apple Music | macOS and the Music app |
Local Files, Subsonic, Internet Radio, YouTube and Qobuz play through spotatui's own audio engine. Apple Music plays in the Music app, and spotatui is its remote. The setup of each source is in Configuration.
Spotify plays in spotatui itself, on any Spotify Connect device, or on Cast and Connect speakers on your network. See Where Spotify plays. For lossless audio, or an account that native streaming cannot play, spotatui can run Spotify's own player: see Soloist.
Learn more
Contributing
spotatui is built by a small team and a growing group of contributors, and you do not need to write code to help. Start with CONTRIBUTING.md, or pick a good first issue.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
