CLI Usage

CLI Usage

Beyond the interactive TUI, spotatui ships a full command-line interface for controlling playback, searching, and managing plugins from your shell or scripts.

spotatui [OPTIONS] [SUBCOMMAND]

Running spotatui with no subcommand launches the TUI.

Top-level flags

Flag	Purpose
-t, --tick-rate <MS>	Override the UI tick rate
-c, --config <PATH>	Use a custom config file
--reconfigure-auth	Re-run the authentication setup wizard
--completions <SHELL>	Print shell completions (bash/zsh/fish/power-shell/elvish)
-U, --no-update	Skip the auto-update check on this launch

The --format flag (on playback, play, list, search) accepts placeholders: %a artist, %b album, %p playlist, %t track, %h show, %f flags, %s status, %v volume, %d device.

playback (alias pb)

Control playback on the active device.

Flag	Purpose
-d, --device <DEVICE>	Target a specific device
-f, --format <FORMAT>	Output format string
-t, --toggle	Pause / resume
-s, --status	Print current playback status (default)
--share-track	Print the current track URL
--share-album	Print the current album URL
--transfer <DEVICE>	Transfer playback to another device
--like / --dislike	Like / unlike the current song
--shuffle	Toggle shuffle
--repeat	Cycle repeat mode
-n, --next	Next track (repeat the flag for multiple skips)
-p, --previous	Previous track (use twice to go to the actual previous)
--seek <±SECONDS>	Seek relative (+10, -10) or absolute (10)
-v, --volume <1-100>	Set the volume

spotatui pb --status
spotatui pb --toggle
spotatui pb --volume 60

play (alias p)

Play a URI, or search by name and play the first match.

Flag	Purpose
-d, --device <DEVICE>	Target device
-f, --format <FORMAT>	Output format
-u, --uri <URI>	Play a Spotify URI directly
-n, --name <NAME>	Search and play the first match (with a type flag)
-q, --queue	Add to the queue instead of playing (tracks only)
-r, --random	Play a random track (playlists only)
-b, --album / -a, --artist / -t, --track / -w, --show / -p, --playlist	Search type

spotatui play --uri spotify:track:...
spotatui play --track --name "bohemian rhapsody"
spotatui play --playlist --name "discover weekly" --random

list (alias l)

List devices, liked songs, or playlists.

Flag	Purpose
-f, --format <FORMAT>	Output format
-d, --devices	List available devices
-p, --playlists	List your playlists
--liked	List liked songs
--limit <1-50>	Maximum results

search (alias s)

Search Spotify.

spotatui search "daft punk" --artists --limit 10

Flag	Purpose
<SEARCH>	Query string (required)
-f, --format <FORMAT>	Output format
-b, --albums / -a, --artists / -p, --playlists / -t, --tracks / -w, --shows	What to search
--limit <1-50>	Maximum results

update

Self-update the spotatui binary (self-update builds).

spotatui update            # check for an update and print the available version
spotatui update --install  # download, verify the checksum, and install

history recap

Generate an HTML listening recap from your local history.

spotatui history recap --period 30d --output recap.html

Flag	Purpose
--period <PERIOD>	7d, 30d (default), month, year, all
-o, --output <PATH>	Output HTML path (default spotatui-recap.html)

plugin

Install and manage Lua plugins — see Lua Plugins for details.

spotatui plugin add owner/repo [--force]
spotatui plugin list            # alias: ls
spotatui plugin remove <NAME>   # alias: rm
spotatui plugin update [NAME]
spotatui plugin new <NAME> [--force]