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 or the current item has ended, Space starts the selected item on Home, Search, Library, or Playlists.

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

Import existing Last.fm history

Preview the import before writing analytics rows:

export SPOTUIFY_LASTFM_API_KEY="lastfm-api-key"
spotuify analytics import lastfm --user your-lastfm-user --from 2024-01-01 --format json

Commit after the fetched, resolved, and unresolved counts look right:

spotuify analytics import lastfm --user your-lastfm-user --from 2024-01-01 --apply --format json