fusor-rs/spotify-tui

spotify-tui is a Spotify player for macOS and Linux. Browse your Liked Songs, playlists and recent plays, search the catalog, and jump to a track's album or artist. Music plays directly on your computer. The installed executable is named spt; the Cargo package is fusor-spotify-tui.

The terminal interface is written in HTML and CSS with Hypercmd and Fusor. Login, browsing and audio use librespot.

In development · v0.1.1 — See status and known limitations.

Get started · Using spotify-tui · How it works · Status · Contributing

You need a Spotify Premium account, a terminal on macOS or Linux, and a browser for the first login. No Spotify developer app or client ID setup is required.

On Linux, audio uses ALSA and login storage requires an unlocked Secret Service provider, such as GNOME Keyring, on your session D-Bus. Install xdg-utils to let the app open the login page in your browser.

The shell installer downloads the latest published GitHub release for x86-64 or ARM64 on macOS or Linux. It verifies the SHA-256 checksum and executable version, then installs spt in ~/.spotify-tui/bin without sudo or a Rust toolchain:

curl -fsSL https://raw.githubusercontent.com/fusor-rs/spotify-tui/main/install.sh | sh
export PATH="$HOME/.spotify-tui/bin:$PATH"
spt

Add the export line to your shell profile, such as ~/.zshrc or ~/.bashrc. Run the installer again to upgrade. To choose a release, append -s -- v0.1.1 to sh, or set SPOTIFY_TUI_VERSION on the sh command. Set SPOTIFY_TUI_INSTALL on that command to choose another install directory; the executable goes in its bin/.

Linux binaries target glibc 2.35 or newer and need the ALSA and OpenSSL 3 runtime libraries, as provided by Ubuntu 22.04 or newer. Alpine's musl runtime is not supported by these archives. The installer requires curl, tar, and either sha256sum or shasum.

This method requires a GitHub release with completed binary uploads.

Install the current stable Rust toolchain through rustup. On Linux, install the build dependencies first; on Debian or Ubuntu:

sudo apt-get update
sudo apt-get install build-essential pkg-config libasound2-dev libssl-dev

On macOS, building requires the Xcode Command Line Tools (xcode-select --install). After the first release is published to crates.io, install with:

cargo install fusor-spotify-tui --locked
spt

--locked uses the release's recorded dependency versions. Cargo installs spt in ~/.cargo/bin by default; that directory needs to be in your PATH. Run the same command again to upgrade. Check your installed version with spt --version.

1. Run spt and choose Log in with Spotify.
2. Approve access in the browser. The terminal continues automatically after the browser returns to http://127.0.0.1:8898/login.
3. Choose a library section or playlist, select a track, and press Enter.

Your login is stored in macOS Keychain or Linux Secret Service, so later starts open your library. Run spt logout to remove the saved login. Upgrading the executable preserves it; macOS can ask you to allow the updated executable to read its keychain item.

With Rust and the platform build dependencies installed:

git clone https://github.com/fusor-rs/spotify-tui.git
cd spotify-tui
cargo install --path . --locked
spt

For development, cargo run --locked builds and launches the app from the checkout.

The sidebar lists your library and playlists. Choose a section to see its tracks, then use the arrow keys and Enter to start playback. Press / or Ctrl+F to search the catalog. With a track selected, press o to open its album or a to open its artist; Escape goes back.

The bar at the bottom shows what's playing. Use its buttons or the keyboard to pause, skip, seek, change volume, shuffle, or cycle repeat modes. Press z to add the selected track to the queue; queued tracks play after the current one. While spt runs, other Spotify apps list this computer as spotify-tui, so you can also control its playback from your phone.

On Linux, spt registers as an MPRIS media player on the session D-Bus, so media keys, desktop widgets, status bars and playerctl control it without switching to the terminal:

playerctl -p spt play-pause
playerctl -p spt next
playerctl -p spt metadata --format '{{ artist }} - {{ title }}'

A second running spt registers as spt.instance<PID>.

Press ? in the player to see the controls. Click the sidebar and playback buttons, or scroll the track list with the mouse wheel.

• Browser login. Spotify's OAuth authorization-code flow uses PKCE and a local callback on 127.0.0.1:8898. The refresh token lives in the system credential store.
• Library and catalog. Playlists, contexts, search and track metadata use Spotify's internal services through a librespot session. The app does not use the public Spotify Web API.
• Local playback. An in-process Spotify Connect speaker streams audio through Rodio. Player events update the now-playing bar.
• HTML views, Rust state. Hypercmd compiles the HTML templates at build time and connects them to Rust state. Templates, styles and embedded assets are included in the crate package.

spotify-tui is in early development and requires Spotify Premium for playback.

Viewing or reordering the queue, media keys on macOS, liking tracks, podcasts and controlling other devices from the terminal are not implemented. Windows is not supported. Spotify's internal services are undocumented and can change independently of this app.

Views and styles live in ui/, application state in src/jukebox/, and login, catalog and playback integration in src/spotify/. Dependency versions are pinned.

Run the checks before submitting a change:

sh -n install.sh
cargo fmt --all -- --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked
cargo publish --locked --dry-run

The Check workflow runs on Linux and macOS for pushes and pull requests. It checks formatting and lints, runs tests, verifies the packaged crate, and launches the executable's help and version commands.

Create a GitHub environment named crates-io with a CARGO_REGISTRY_TOKEN secret authorized to publish fusor-spotify-tui. Commit the release version in Cargo.toml and Cargo.lock, then publish a GitHub release with the matching vVERSION tag, such as v0.1.1.

The Release workflow runs Check, validates the tag against the manifest, and builds x86-64 and ARM64 executables on Linux and macOS. Linux builds use Ubuntu 22.04 with GNU targets to link the audio and TLS libraries. Each archive contains spt, LICENSE, and README.md in a directory named spotify-tui-VERSION-TARGET. Archives have a .tar.gz extension and an accompanying .tar.gz.sha256 checksum file.

Each build uses install.sh to verify, install and run its executable before uploading artifacts. It also checks that a corrupt download leaves the installed executable unchanged. SPOTIFY_TUI_DOWNLOAD_BASE points the installer at local archives during these checks.

After all builds pass, the workflow attaches the archives to the GitHub release and publishes the crate to crates.io. Reruns skip an already published crate version and replace release assets. The installer is attached after both steps succeed. Running Release manually verifies the crate and produces binary workflow artifacts without publishing a crate or uploading GitHub release assets.

Licensed under the MIT License.