spotatui

spotatui [options] [command]

spotatui is a terminal music player written in Rust. With no command it opens a full-screen interface. Press ? inside the player for the key list, and q to go back or quit.Spotify is optional. The same player can use local files, a Subsonic or Navidrome server, internet radio, YouTube, Qobuz, and, on macOS, Apple Music. Press d to switch source or pick a Spotify Connect device.Spotify audio comes from one of three places: spotatui itself, registered as its own Connect device; the official Spotify app; or spotifyd. A Spotify login needs a Premium account. No developer client id is required. Local files, Subsonic, radio, YouTube, and Qobuz play through spotatui's own audio engine. Apple Music plays through the Music app.playback, play, search, and list are separate Spotify commands. They use the cached login and do not need the full-screen player to be open. File, YouTube, Qobuz, Subsonic, radio, and Apple Music items play from inside the running player.

-c, --config PATH

Read this configuration file instead of the default.

UI refresh interval in milliseconds. Animated views keep their own rate.

Forget the cached Spotify login and sign in again.

Play a local audio file on startup. Needs a build with the local-files feature. Release binaries include it.

Print completions for bash, zsh, fish, powershell, or elvish. power-shell is accepted as an old spelling.

Log at debug level, including the Spotify user id and playlist ids. SPOTATUI_LOG=debug does the same. SPOTATUI_LOG=trace also records API response bodies, which include the account country. Access tokens and request headers are not logged.

Skip the startup update check on builds that include the updater. The check is also skipped when SPOTATUI_SKIP_UPDATE is set, or when behavior.disable_auto_update is true.

Show help. Add it after a command to show that command.

The file is `$XDGCONFIGHOME/spotatui/config.yml` when that variable is an absolute path, and `~/.config/spotatui/config.yml` otherwise. --config replaces it. Every field is optional.Runtime state (volume, shuffle, active source, saved Spotify device, pane sizes, saved radio stations, and listening history) is `$XDGSTATEHOME/spotatui/state.yml`, or `~/.local/state/spotatui/state.yml`. The Spotify login and the streaming audio cache live under `$XDGCACHEHOME/spotatui/`, or `~/.cache/spotatui/`.A bad value usually logs a warning and falls back to the default. YAML that cannot be parsed stops startup. So do a few numbers outside their range, including `volume_increment` outside 0–100 and a tick rate outside 1–999 ms.Each run writes a log at `spotatuilogs/spotatuilog` plus the process id, under the system temp directory. The path is printed at startup. A panic also writes `spotatuipanic.log` in the state directory.

$ behavior:
  enable_streaming: true
  streaming_device_name: spotatui
  streaming_bitrate: 320
  local_music_path: "[/path/to/Music]"
  seek_milliseconds: 5000
  volume_increment: 10
keybindings:
  toggle_playback: " "
  back: "q"

spotatui playback (alias pb) controls a Spotify device. With no action it prints the current playback, and it prints the updated playback after every action. --format changes that line. The default is `%f %s %t - %a`.Placeholders: %a artist, %b album, %t track, %p playlist, %h show, %f shuffle, repeat, and like flags, %s play or pause, %v volume, %d device, %u URI, %r progress.-d, --device DEVICE

Spotify device to use.

Pause or resume.

Print status. This is the default.

Skip forward one track. Repeat the flag to skip further: `spotatui pb -nnn` skips three.

Once jumps to the start of the current track. Twice (`-pp`) goes to the previous track.

`+10` seeks forward, `-10` seeks backward, and `10` seeks to that second of the track.

Set the device volume.

Toggle shuffle.

Cycle repeat modes.

Save the current track when Spotify allows it.

Remove that save.

Move playback to another device.

Print the open.spotify.com URL of the current track. Use it alone.

Print the URL of its album. Use it alone.

spotatui play (alias p) starts the first Spotify match, or a Spotify URI. The first hit plays with no confirmation prompt.-u, --uri URI

Play a `spotify:track:`, `spotify:album:`, `spotify:artist:`, `spotify:playlist:`, or `spotify:show:` URI. Web URLs and every other scheme are rejected.

Play the first hit of this name. Requires one of the type flags below.

Search tracks.

Search albums.

Search artists.

Search playlists.

Search shows.

Append a track to the queue instead of playing it. Tracks only.

Play a random track from a playlist.

Target device.

Status line after the action. Same placeholders as playback. The default is `%f %s %t - %a`.

spotatui search (alias s) searches Spotify. The query is a required positional argument, and exactly one type flag is required. --limit accepts 1 to 10.

$ spotatui search --albums "[query]"

Search tracks. Default format `%t - %a (%u)`.

Search albums. Default format `%b - %a (%u)`.

Search artists. Default format `%a (%u)`.

Search playlists. Default format `%p (%u)`.

Search shows. Default format `%h - %a (%u)`.

One line per hit. Same placeholders as playback.

Maximum number of results, from 1 to 10.

spotatui list (alias l) prints Spotify devices, playlists, or liked songs. Exactly one of those flags is required. --limit accepts 1 to 50.--devices

List devices. Default format `%v% %d`.

List playlists. Default format `%p (%u)`.

List liked songs. Default format `%t - %a (%u)`.

Maximum number of results, from 1 to 50.

One line per item.

history recap

Write an HTML page from the local listening history. --period is `7d`, `30d` (the default), `month`, `year`, or `all`. -o sets the output path. The default file is `spotatui-recap.html` in the working directory.

Mirror playlists that were linked inside the player. Runs without probing for a Spotify device. --link NAME limits the run to one master playlist name or id. --dry-run prints the changes and writes nothing.

Install Lua plugins with git into the config directory. add takes `owner/repo` or a git URL, and -f reinstalls an existing copy. list (alias ls) shows what is installed. update refreshes every plugin, or the named one. remove (alias rm) deletes one. new scaffolds a plugin, and -f overwrites a directory of the same name. Restart the player after installing. Plugins load at startup and are not sandboxed.

Speak the Model Context Protocol on stdin and stdout so a client can drive a running player. Bare `spotatui mcp` is the server and blocks, waiting for JSON-RPC. mcp status checks the setup and exits. mcp status --json prints JSON. The player must already be running with `behavior.mcp_enabled: true`.

Check for a new release. --install downloads and installs it. Present on builds that include the updater, including the release binaries.

Defaults. Rebind them under `keybindings` in the config file. Press ? for the full list. The help menu hides actions the current source cannot perform.Space

Play or pause.

Next track, or previous track. P forces the previous track and skips restoring the play position.

Seek. The step is `behavior.seek_milliseconds` (default 5000).

Volume, in steps of `behavior.volume_increment` (default 10).

Search.

Switch source or choose a playback device.

Add the selected item to the queue. Q shows the queue. x removes an entry.

Like or save the track.

Audio visualization. V switches style and cannot be rebound.

Lyrics. T opens the mini player. G opens cover art on builds that include it. Release binaries include cover art.

Shuffle and repeat.

Move through lists. The arrow keys do the same.

Back, or quit from the top screen.

Open settings. On macOS the default is Ctrl-,. Alt-s saves them.

The Spotify login refuses a free account. Premium is required for the Spotify source. Playback still needs native streaming, the official app, or spotifyd to produce the audio.`play --uri` accepts only the five Spotify URI kinds listed above. `file:`, `youtube:`, `qobuz:`, `subsonic:`, `radio:`, and `applemusic:` URIs, and `https://open.spotify.com` links, are rejected there.`cargo install --locked spotatui` leaves out local files, Subsonic, radio, YouTube, Qobuz, and Apple Music unless those Cargo features are turned on. The release binaries, the one-line installer, and `cargo binstall` include them. Apple Music exists only on macOS.The system-wide visualizer reads a loopback of all system audio. Linux uses a PipeWire or PulseAudio monitor. macOS needs a virtual audio device set as the input. While a Spotify track plays, v opens Spotify's own pitch view, which needs no loopback.A release build looks for an update at startup and can replace its own binary. --no-update skips that check.Lua plugins run with the player's privileges, including the filesystem and the network. Installing one clones a git repository and runs its `main.lua` on the next start. There is no permission prompt.--debug logs can contain a Spotify user id and playlist ids. Read the file before attaching it to a public report.

spotatui is a community-maintained fork of spotify-tui, whose command is spt. The fork adds a built-in Spotify Connect client and playback from local files, Subsonic, internet radio, YouTube, Qobuz, and Apple Music on macOS. It is released under the MIT license. The GitHub repository was published in November 2025.

ncspot(1), spotify_player(1), spt(1), spotifyd(1), cmus(1), yt-dlp(1)

Source code · Homepage · Documentation