Beyond the terminal UI, spotatui has a command-line interface for playback, search, playlists, sync and plugins.
spotatui [OPTIONS] [SUBCOMMAND]Running spotatui with no subcommand starts the terminal UI. spotatui --help and spotatui <subcommand> --help list every flag.
| Flag | Purpose |
|---|---|
-t, --tick-rate <MS> |
UI tick rate, 1 to 999 ms |
-c, --config <PATH> |
Use another config file |
--reconfigure-auth |
Forget the cached Spotify login and log in again |
--completions <SHELL> |
Print shell completions: bash, zsh, fish, powershell or elvish |
--play-file <PATH> |
Play a local audio file at startup (local-files builds) |
--debug |
Verbose logging for a bug report, see Logging |
-U, --no-update |
Skip the auto-update check for this launch (self-update builds) |
--format (on playback, play, list and search) takes these placeholders: %a artist, %b album, %p playlist, %t track, %h show, %u URI, %f flags, %s status, %v volume, %d device, %r progress.
Control playback on the active device. With no flag it prints the status.
| Flag | Purpose |
|---|---|
-d, --device <NAME> |
Target a device by name |
-t, --toggle |
Pause or resume |
-s, --status |
Print the playback status |
--share-track / --share-album |
Print the URL of the current track or album (use alone) |
--transfer <NAME> |
Move playback to another device |
--like / --dislike |
Like or unlike the current track |
--shuffle |
Toggle shuffle |
--repeat |
Cycle the repeat mode |
-n, --next |
Next track (repeat the flag to skip more) |
-p, --previous |
Previous track (twice goes to the actual previous track) |
--seek <±SECONDS> |
Seek relative (+10, -10) or absolute (10) |
-v, --volume <0-100> |
Set the volume |
--next and --previous cannot be combined with other flags.
spotatui pb --toggle
spotatui pb --volume 60Play a Spotify URI, or search by name and play the first match. Give exactly one of --uri or --name.
| Flag | Purpose |
|---|---|
-u, --uri <URI> |
A spotify:track:, album:, artist:, playlist: or show: URI |
-n, --name <NAME> |
Search and play the first match; needs one type flag below |
-b, --album / -a, --artist / -t, --track / -w, --show / -p, --playlist |
What to search for |
-q, --queue |
Queue the track instead of playing it (tracks only) |
-r, --random |
Play a random track (playlists only) |
-d, --device <NAME> |
Target a device by name |
spotatui play --track --name "bohemian rhapsody"
spotatui play --playlist --name "Your Playlist" --random| Flag | Purpose |
|---|---|
-d, --devices |
List devices |
-p, --playlists |
List your playlists |
--liked |
List your liked songs |
--limit <1-50> |
Maximum results |
spotatui list --liked --limit 50spotatui search "daft punk" --artists --limit 10| Flag | Purpose |
|---|---|
<SEARCH> |
The query |
-b, --albums / -a, --artists / -p, --playlists / -t, --tracks / -w, --shows |
What to search |
--limit <1-10> |
Maximum results |
Sync the linked playlists across sources (see Playlist sync). It needs no Spotify device and exits non-zero when the sync fails.
| Flag | Purpose |
|---|---|
--link <NAME> |
Only the link with this master playlist name or id |
--dry-run |
Report what would change, write nothing |
Make a shareable HTML recap from your local listening history.
spotatui history recap --period 30d --output recap.html| Flag | Purpose |
|---|---|
--period <PERIOD> |
7d, 30d (default), month, year or all |
-o, --output <PATH> |
Output file (default spotatui-recap.html) |
The MCP server for coding agents (mcp-server builds, which include every prebuilt terminal binary; the desktop app has no spotatui mcp). spotatui mcp is the stdio server an agent starts; spotatui mcp status checks the setup and exits non-zero when it is not ready (--json for machine-readable output). See MCP setup.
Install and manage Lua plugins (needs git). See Scripting.
spotatui plugin add owner/repo [--force] # or a full git URL
spotatui plugin list # alias: ls
spotatui plugin remove <NAME> # alias: rm
spotatui plugin update [NAME]
spotatui plugin new <NAME> [--force]Self-update builds only.
spotatui update # print the current and the latest version
spotatui update --install # download, check, and install the latest version (-i)