Quick Start

This page is the shortest path from a working install to music.

Open the TUI

spotuify

What you get: the player-first terminal UI. Press /, type a query, press Enter, then press Enter on a result to play it. Home also has playable saved music and podcasts as soon as the cache is warm; if nothing is playing, Space starts the selected Home item.

Play without the TUI

spotuify play "imagine dragons"

What you get: a mutation receipt. Use --format json when a script or agent needs to read it.

spotuify play "imagine dragons" --format json

Pick with fzf

spotuify search "luther vandross" --type track --format ids \
  | fzf \
  | xargs spotuify play-uri

What you get: one Spotify URI selected from search and sent back into playback.

Queue the first match

spotuify queue add --search "never too much"
spotuify queue --format json

Add the current track to a playlist

spotuify playlist add-current "Coding"

Use a dry-run before playlist writes

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

Commit after the preview looks right:

spotuify playlist add "Coding" spotify:track:4uLU6hMCjMI75M1A2tKUQC --yes

Ask an agent for music

Prompt:

Make me an upbeat but focused playlist. Use spotuify playlist plan,
resolve-tracks, then show playlist create --dry-run before changing Spotify.

Commands the agent should run:

spotuify playlist plan "upbeat but focused" --format json > plan.json
spotuify resolve-tracks --from plan.json --format jsonl > candidates.jsonl
spotuify playlist create "Upbeat Focus" --from candidates.jsonl --dry-run