Prompster

Prompster is a Go CLI for building printable Hitster-style decks from Spotify. It searches Spotify, uses playlists in the signed-in user's account as decks, and renders those playlists as duplex-ready PDF cards with Spotify QR codes. It also exposes full Spotify playback, library, and playlist commands.

Design idea

Prompster is built to be driven by an AI CLI agent (Claude Code, Codex, or similar) as much as by a human typing commands directly. The idea: you describe the deck you want in conversation — "make me an 80s party Hitster deck with 40 songs" — and the agent plans searches, builds the playlist, and exports the PDF by calling Prompster commands on your behalf, asking you to confirm or pick between ambiguous results along the way.

That's why Prompster is built as a scriptable CLI rather than an interactive TUI: an agent can drive it as reliably as a human can.

   

Table of contents

• Install
• Quick start
• Global flags
• API reference
  • auth
  • search
  • playlist
  • deck
  • Playback
  • device
  • completion
• Configuration
• License

Install

Download an archive for Windows, macOS, or Linux from GitHub Releases. Official release binaries contain Typst 0.15.1, so PDF export does not require a separate Typst installation.

To build from source with the pinned compiler embedded:

make build

make build downloads the pinned Typst release assets when necessary. All Prompster builds are self-contained; external Typst installations and runtime overrides are intentionally unsupported.

Quick start

Prompster authenticates against Spotify's official Web API via OAuth. Create an app in the Spotify Developer Dashboard, add a redirect URI (e.g. http://127.0.0.1:8888/callback), then:

prompster auth setup --client-id <id> --redirect-uri http://127.0.0.1:8888/callback
prompster auth login
prompster auth status

A client secret is optional — Prompster uses the Authorization Code flow with PKCE, which works for public (secret-less) apps too.

Create a deck as a real Spotify playlist, then add Spotify IDs, URLs, or URIs:

prompster search track "Daft Punk One More Time" --limit 5
prompster deck create "Friday Night"
prompster deck add <playlist> spotify:track:0DiWol3AO6WpXZgp0goxAV

prompster search playlist "80s party" --limit 5
prompster playlist tracks 37i9dQZF1DXb57FjYWz00c --limit 25 --offset 0

Edit and export the Spotify-backed deck:

prompster deck remove <playlist> 0DiWol3AO6WpXZgp0goxAV
prompster deck replace <playlist> OLD_TRACK_ID=NEW_TRACK_ID
prompster deck lint <playlist> --json
prompster deck export <playlist> --output friday-night.pdf

The Spotify playlist is the only persistence layer: users can inspect, reorder, and listen to it in Spotify before exporting. Prompster stores no local deck or track metadata cache. PDF export accepts playlists with up to 300 tracks.

Global flags

Global flags may appear before the command. Every flag also has a PROMPSTER_* environment variable equivalent.

Flag	Env var	Description
--config <path>	PROMPSTER_CONFIG	Config file path
--profile <name>	PROMPSTER_PROFILE	Isolated authentication/config profile
--market <cc>	PROMPSTER_MARKET	Spotify market country code
--language <locale>	PROMPSTER_LANGUAGE	Language/locale for API responses
--device <name|id>	PROMPSTER_DEVICE	Playback target device
--timeout <duration>	PROMPSTER_TIMEOUT	HTTP timeout (default 10s)
--json	PROMPSTER_JSON	Machine-readable JSON output
--plain	PROMPSTER_PLAIN	Tab-separated plain output
--no-color	PROMPSTER_NO_COLOR	Disable ANSI color output
-q, --quiet	PROMPSTER_QUIET	Suppress non-essential output
-v, --verbose	PROMPSTER_VERBOSE	Verbose output
-d, --debug	PROMPSTER_DEBUG	Debug output
--no-input	PROMPSTER_NO_INPUT	Disable interactive prompts
--version	—	Print the Prompster version

--json and --plain are mutually exclusive. Without either, Prompster prints human-readable, colorized output.

API reference

Every command accepts --json or --plain for scripting. IDs accept a bare Spotify ID, a spotify:<type>:<id> URI, or an open.spotify.com URL, wherever "ID/URL/URI" is noted below.

auth

Authenticates against the official Spotify Web API via OAuth Authorization Code + PKCE.

Command	Flags	Description
auth setup	--client-id, --client-secret, --redirect-uri	Persists Spotify Developer app credentials for the active profile. --client-id is required unless already saved or set via PROMPSTER_CLIENT_ID.
auth login	—	Opens the Spotify OAuth consent screen in your browser and captures the redirect on a local server.
auth status	—	Prints login state, granted scope, and token expiry.
auth logout	—	Clears the stored session for the active profile.

search

prompster search track <query> [--limit 1-50] [--offset 0]
prompster search playlist <query> [--limit 1-50] [--offset 0]

Multi-word queries don't need quoting. Default --limit is 20, capped at 50.

playlist

Operates on any playlist the authenticated user can read or write.

Command	Args	Flags	Description
playlist create <name>	playlist name	--public, --collab	Creates a playlist. Private, non-collaborative by default.
playlist add <playlist> <track>...	playlist + one or more tracks	—	Appends tracks to a playlist.
playlist remove <playlist> <track>...	playlist + one or more tracks	—	Removes all occurrences of each track from a playlist.
playlist tracks <playlist>	playlist	--limit (default 50), --offset	Lists a playlist's tracks, paginated.

Playlist reads are paginated — start at offset zero and request later pages only when needed. Search and playlist inspection never create local state or alter a playlist.

deck

A deck is a regular Spotify playlist used as the source for a printable card set — deck is a thin wrapper around playlist plus PDF export, capped at 300 tracks.

Command	Args	Flags	Description
deck create <name>	deck name	--public, --collab	Creates the backing Spotify playlist.
deck add <playlist> <track>...	playlist + one or more tracks	—	Adds tracks to the deck; refuses to exceed the 300-track limit.
deck remove <playlist> <track>...	playlist + one or more tracks	—	Removes tracks from the deck.
deck replace <playlist> <old>=<new>...	playlist + one or more OLD=NEW pairs	—	Swaps tracks in place: adds the new tracks first, then removes the old ones, so a failed swap never loses existing tracks.
deck lint <playlist>	playlist	--min-year-span, --max-artist-share, --max-decade-share	Read-only sanity check for duplicates, year/decade spread, artist concentration, and deck diversity.
deck export <playlist>	playlist	-o, --output (default deck.pdf), --page-limit (default: all pages)	Renders the deck as duplex-ready PDF cards: QR-code fronts and mirrored song/artist/year backs, 12 cards (4x3, 6 cm) per A4 sheet.

deck create immediately creates a playlist in the authenticated Spotify account. That playlist is the deck's only persistence and can be inspected, reordered, and played in Spotify. Prompster keeps no local deck JSON or metadata cache.

Playback

Playback commands are top-level — there is no prompster playback parent command.

Command	Args	Flags	Description
play [<id|url|uri>]	optional item	--type, --shuffle	With no argument, resumes playback. A track/episode plays directly; album/playlist/show start context playback; an artist plays its top track. A bare ID needs --type to disambiguate.
pause	—	—	Pauses playback.
next	—	—	Skips to the next track.
prev	—	—	Skips to the previous track.
seek <position>	position (ms or mm:ss)	—	Seeks within the current track.
volume <0-100>	percent	—	Sets playback volume.
shuffle <on|off>	—	—	Toggles shuffle.
repeat <off|track|context>	—	—	Sets repeat mode.
status	—	—	Shows the current track, position, device, volume, shuffle, and repeat state.

--device (global flag) targets a device ID or name from device list; omitted, Spotify uses whatever device it considers active.

device

Command	Args	Description
device list	—	Lists available Spotify Connect devices.
device set <name|id>	device name or ID	Transfers playback to the given device.

completion

prompster completion <bash|zsh|fish>

Prints shell completion code for the given shell.

Configuration

Prompster stores OAuth tokens below the operating system's user config directory, separated by --profile. Never commit token files or paste them into issue reports.

This tool interacts with Spotify's official Web API. Use it responsibly and in accordance with Spotify's Terms of Service.

License

Prompster is licensed under the MIT License.