Queue and Playlists

Queue changes are quick. Playlist changes are durable, so broad writes should preview first.

Save or remove one library item

spotuify like spotify:track:4uLU6hMCjMI75M1A2tKUQC --wait
spotuify unlike spotify:track:4uLU6hMCjMI75M1A2tKUQC --wait

--wait blocks until the provider confirms the write and returns a non-zero exit code on failure. unlike is reversible by running like with the same resource.

Show the queue

spotuify queue
spotuify queue --format json

Add one item

spotuify queue add spotify:track:4uLU6hMCjMI75M1A2tKUQC

Add by search:

spotuify queue add --search "never too much"

The TUI append behavior is the same product rule: queueing a track appends one URI; queueing a playlist or album expands it to playable tracks and appends them. It does not replace the current queue.

The queue is a set: a track appears at most once. Adding a URI that is already queued is skipped, and the receipt says so (skipped N already queued). Spotify has no queue-move, so the existing entry stays where it is rather than moving up. Queue adds are also not undoable; Spotify has no queue-remove endpoint, so ops undo refuses them instead of pretending.

spotuify queue

After tracks enter the queue, the daemon starts a best-effort background warm for those URIs. It resolves metadata, caches cover art, warms lyrics, indexes the items, and asks the embedded player to preload the next audio URI when that backend supports it. The queue command does not wait for this work.

Queueing when nothing is playing

The queue lives on the active Spotify session, so there has to be one. When the provider reports no active session, spotuify starts the embedded device. For a playlist or album it loads the complete resolved, deduplicated track list into the native player, with the first item current and the remainder up next. For individual selections it starts the first item and appends the others:

spotuify queue add --search "never too much"   # idle → it starts playing

What you get: a session on the configured local Connect device, with the remaining items queued. A paused active Spotify session is still a session: queueing can append without resuming it. Once a session exists, queue add appends as usual.

List playlists to obtain the URI, then inspect its tracks before adding it. Replace the example URI with one from your playlist list:

spotuify playlists --format json
playlist_uri=spotify:playlist:37i9dQZF1DXcBWIGoYBM5
spotuify playlist tracks "$playlist_uri" --format json
spotuify queue add "$playlist_uri" --wait --format json
spotuify queue --format json

Queue adds have no --dry-run flag and cannot be undone through Spotify’s public queue API. --wait waits for mutation finalization and reports failure; it is not an audible-start barrier. An embedded load can be accepted before native playback starts. Confirm the playing track and audio before requesting reconnect or another session-changing operation:

spotuify status --format json | jq '{uri: .item.uri, is_playing, progress_ms, source}'
spotuify daemon status --format json | jq .audio_health
spotuify viz status --format json

For local playback, check advancing progress, samples_advancing, and fresh sink frames. A confirmed receipt or one is_playing: true sample does not establish sustained audio. Playback troubleshooting explains the health checks.

In the TUI, Enter replaces the queue with the item you picked and starts playback. e appends. A toast after Enter reminds you of the alternative:

Playing Wonderwall (queue replaced · e to enqueue next time)

If you wanted to append, Esc dismisses the toast, then re-select and press e. Queue changes are not undoable (Spotify has no queue-remove), so the replace is final; rebuild the queue from search or a playlist if you change your mind.

List playlists

spotuify playlists
spotuify playlists --format ids

Show playlist tracks

spotuify playlist tracks "Quiet Storm" --format jsonl

Play a playlist

spotuify playlist play "Quiet Storm"

Playing an album or playlist context publishes a daemon queue snapshot. The first context track appears as the current item; the rest appear as up next. That snapshot is cached and broadcast, so Home, Queue, the queue rail, CLI watchers, MCP clients, and agents all see the same context queue instead of an empty queue.

In the TUI, Enter on a playlist or playlist track uses the same context-play path. Space does too when there is no resumable current item.

Add with a dry-run

spotuify playlist add "Quiet Storm" spotify:track:4uLU6hMCjMI75M1A2tKUQC --dry-run

In the TUI, press a or A on a selected item. A playlist picker opens; use Space to select one or more playlists, then Enter to add.

spotuify playlist add "Quiet Storm" spotify:track:4uLU6hMCjMI75M1A2tKUQC --dry-run

Commit only after the preview:

spotuify playlist add "Quiet Storm" spotify:track:4uLU6hMCjMI75M1A2tKUQC --yes

Remove exact rows

URI-based removal remains available:

spotuify playlist remove "Quiet Storm" spotify:track:4uLU6hMCjMI75M1A2tKUQC --dry-run

Use one-based row numbers when the same URI appears more than once and you need to choose the exact occurrences:

spotuify playlist remove-at "Quiet Storm" 2 5 --dry-run
spotuify playlist remove-at "Quiet Storm" 2 5 --yes

The daemon checks those rows against a fresh full-playlist read before the write. In the TUI, open the playlist, mark rows with m, then press Delete. The confirmation freezes the marked rows; the daemon owns the resulting state and position-aware undo when the provider supplies playlist version tokens.

Agent playlist workflow

spotuify playlist plan "exile and returning home" --format json > plan.json
spotuify resolve-tracks --from plan.json --format jsonl > candidates.jsonl
spotuify playlist create "Exile and Return" --from candidates.jsonl --dry-run

After approval:

spotuify playlist create "Exile and Return" --from candidates.jsonl --yes --format json

What you get: a receipt with playlist id, playlist URI, playlist name, and added item count.

spotuify playlist create "Exile and Return" --from candidates.jsonl --yes --format json