How to use spotify-tui: install, connect and control Spotify

Install spotify-tui

The binary executable is named spt. The project lists several install routes, depending on your system. The simplest on macOS or Linux is Homebrew, and Cargo works on any system where you can build Rust code.

• Homebrew (macOS and Linux): use the package manager route below.
• Snap, AUR helper, Nix, Scoop or Void Linux and Fedora/CentOS packages are also listed in the README.
• Cargo: install Rust with rustup first, then build from source. On Linux you also need the libssl development packages and pkg-config.

Build from source with Cargo

Use this route if your architecture is not covered by the pre-built binaries on the releases page. Install Rust using the recommended rustup method, then run the install command. To update, run the same command again.

• On Linux, install the development packages for libssl and pkg-config before building.
• On Windows Subsystem for Linux, the README says you need additional dependencies.

Create a Spotify developer app and get your credentials

spotify-tui controls Spotify through Spotify's API, so it needs your own API credentials. The first time you run the app it asks for them, but the README also lists the steps to follow in advance.

• Open the Spotify dashboard at developer.spotify.com/dashboard/applications.
• Click Create an app. You will then see your Client ID and Client Secret.
• Click Edit Settings and add http://localhost:8888/callback to the Redirect URIs.
• Scroll down and click Save.

Authenticate on first run

Run spt in your terminal. The app asks you for your Client ID and Client Secret, then for a port. Press enter to accept the default port 8888 or type a custom one.

• Accept the permissions on the official Spotify page you are sent to.
• You are redirected to localhost. If the local server works, the redirect is handled automatically.
• If the local server fails, you may see a blank or Connection Refused page. Copy the full URL from the address bar and paste it into the prompt in the terminal.

Use the interface and the spt command

Running spt with no arguments opens the UI. Press ? to see a help menu listing the key events and what they do. The CLI can do most of what the UI does; run spt --help for the full list of options.

The README gives these examples of CLI actions: playing a playlist at random, playing a named track, liking the current song, toggling shuffle, play or pause, listing liked songs and searching with a custom output format.

• Play a random song from a playlist: spt play --name "Your Playlist" --playlist --random
• Like the current song and toggle shuffle: spt playback --like --shuffle
• Play or pause: spt playback --toggle
• List liked songs (50 is the max limit): spt list --liked --limit 50
• Print shell completions for zsh: spt --completions zsh

Change settings in the config files

Your API credentials are stored in client.yml. Display and behaviour options live in config.yml. Both are in a spotify-tui folder under your home .config directory. Snap installs use a different path under snap/spt.

• client.yml: Spotify authentication. Edit it at any time.
• config.yml: theme colours and behaviour settings such as seek_milliseconds (sample value 5000) and volume_increment (sample value 10).
• Snap paths: ${HOME}/snap/spt/current/.config/spotify-tui/