Pp Spotify

Spotify — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the spotify-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install spotify --cli-only
   

2. Verify: spotify-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/spotify/cmd/spotify-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

You can use Spotify's Web API to discover music and podcasts, manage your Spotify library, control audio playback, and much more. Browse our available Web API endpoints using the sidebar at left, or via the navigation bar on top of this page on smaller screens.

In order to make successful Web API requests your app will need a valid access token. One can be obtained through OAuth 2.0.

The base URI for all Web API requests is https://api.spotify.com/v1.

Need help? See our Web API guides for more information, or visit the Spotify for Developers community forum to ask questions and connect with other developers.

Command Reference

albums — Manage albums

• spotify-pp-cli albums get-an — Get Spotify catalog information for a single album.
• spotify-pp-cli albums get-multiple — Get Spotify catalog information for multiple albums identified by their Spotify IDs.

artists — Manage artists

• spotify-pp-cli artists get-an — Get Spotify catalog information for a single artist identified by their unique Spotify ID.
• spotify-pp-cli artists get-multiple — Get Spotify catalog information for several artists based on their Spotify IDs.

audio-analysis — Manage audio analysis

• spotify-pp-cli audio-analysis <id> — Get a low-level audio analysis for a track in the Spotify catalog.

audio-features — Manage audio features

• spotify-pp-cli audio-features get — Get audio feature information for a single track identified by its unique Spotify ID.
• spotify-pp-cli audio-features get-several — Get audio features for multiple tracks based on their Spotify IDs.

audiobooks — Manage audiobooks

• spotify-pp-cli audiobooks get-an — Get Spotify catalog information for a single audiobook.
• spotify-pp-cli audiobooks get-multiple — Get Spotify catalog information for several audiobooks identified by their Spotify IDs.

browse — Manage browse

• spotify-pp-cli browse get-a-categories-playlists — Get a list of Spotify playlists tagged with a particular category.
• spotify-pp-cli browse get-a-category — Get a single category used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).
• spotify-pp-cli browse get-categories — Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).
• spotify-pp-cli browse get-featured-playlists — Get a list of Spotify featured playlists (shown, for example, on a Spotify player's 'Browse' tab).
• spotify-pp-cli browse get-new-releases — Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “Browse” tab).

chapters — Manage chapters

• spotify-pp-cli chapters get-a — Get Spotify catalog information for a single audiobook chapter.
• spotify-pp-cli chapters get-several — Get Spotify catalog information for several audiobook chapters identified by their Spotify IDs.

episodes — Manage episodes

• spotify-pp-cli episodes get-an — Get Spotify catalog information for a single episode identified by its unique Spotify ID.
• spotify-pp-cli episodes get-multiple — Get Spotify catalog information for several episodes based on their Spotify IDs.

markets — Manage markets

• spotify-pp-cli markets — Get the list of markets where Spotify is available.

me — Manage me

• spotify-pp-cli me add-to-queue — Add an item to be played next in the user's current playback queue.
• spotify-pp-cli me check-current-user-follows — Check to see if the current user is following one or more artists or other Spotify users.
• spotify-pp-cli me check-library-contains — Check if one or more items are already saved in the current user's library.
• spotify-pp-cli me check-users-saved-albums — Check if one or more albums is already saved in the current Spotify user's 'Your Music' library.
• spotify-pp-cli me check-users-saved-audiobooks — Check if one or more audiobooks are already saved in the current Spotify user's library.
• spotify-pp-cli me check-users-saved-episodes — Check if one or more episodes is already saved in the current Spotify user's 'Your Episodes' library.
• spotify-pp-cli me check-users-saved-shows — Check if one or more shows is already saved in the current Spotify user's library.
• spotify-pp-cli me check-users-saved-tracks — Check if one or more tracks is already saved in the current Spotify user's 'Your Music' library.
• spotify-pp-cli me create-playlist — Create a playlist for the current Spotify user.
• spotify-pp-cli me follow-artists-users — Add the current user as a follower of one or more artists or other Spotify users. Note: This endpoint is deprecated.
• spotify-pp-cli me get-a-list-of-current-users-playlists — Get a list of the playlists owned or followed by the current Spotify user.
• spotify-pp-cli me get-a-users-available-devices — Get information about a user’s available Spotify Connect devices.
• spotify-pp-cli me get-current-users-profile — Get detailed profile information about the current user (including the current user's username).
• spotify-pp-cli me get-followed — Get the current user's followed artists.
• spotify-pp-cli me get-information-about-the-users-current-playback — Get information about the user’s current playback state, including track or episode, progress, and active device.
• spotify-pp-cli me get-queue — Get the list of objects that make up the user's queue.
• spotify-pp-cli me get-recently-played — Get tracks from the current user's recently played tracks. Note: Currently doesn't support podcast episodes.
• spotify-pp-cli me get-the-users-currently-playing-track — Get the object currently being played on the user's Spotify account.
• spotify-pp-cli me get-users-saved-albums — Get a list of the albums saved in the current Spotify user's 'Your Music' library.
• spotify-pp-cli me get-users-saved-audiobooks — Get a list of the audiobooks saved in the current Spotify user's 'Your Music' library.
• spotify-pp-cli me get-users-saved-episodes — Get a list of the episodes saved in the current Spotify user's library.
• spotify-pp-cli me get-users-saved-shows — Get a list of shows saved in the current Spotify user's library.
• spotify-pp-cli me get-users-saved-tracks — Get a list of the songs saved in the current Spotify user's 'Your Music' library.
• spotify-pp-cli me get-users-top-artists — Get the current user's top artists based on calculated affinity.
• spotify-pp-cli me get-users-top-tracks — Get the current user's top tracks based on calculated affinity.
• spotify-pp-cli me pause-a-users-playback — Pause playback on the user's account. This API only works for users who have Spotify Premium.
• spotify-pp-cli me remove-albums-user — Remove one or more albums from the current user's 'Your Music' library. Note: This endpoint is deprecated.
• spotify-pp-cli me remove-audiobooks-user — Remove one or more audiobooks from the Spotify user's library. Note: This endpoint is deprecated.
• spotify-pp-cli me remove-episodes-user — Remove one or more episodes from the current user's library. Note: This endpoint is deprecated.
• spotify-pp-cli me remove-library-items — Remove one or more items from the current user's library.
• spotify-pp-cli me remove-shows-user — Delete one or more shows from current Spotify user's library. Note: This endpoint is deprecated.
• spotify-pp-cli me remove-tracks-user — Remove one or more tracks from the current user's 'Your Music' library. Note: This endpoint is deprecated.
• spotify-pp-cli me save-albums-user — Save one or more albums to the current user's 'Your Music' library. Note: This endpoint is deprecated.
• spotify-pp-cli me save-audiobooks-user — Save one or more audiobooks to the current Spotify user's library. Note: This endpoint is deprecated.
• spotify-pp-cli me save-episodes-user — Save one or more episodes to the current user's library. Note: This endpoint is deprecated.
• spotify-pp-cli me save-library-items — Add one or more items to the current user's library.
• spotify-pp-cli me save-shows-user — Save one or more shows to current Spotify user's library. Note: This endpoint is deprecated.
• spotify-pp-cli me save-tracks-user — Save one or more tracks to the current user's 'Your Music' library. Note: This endpoint is deprecated.
• spotify-pp-cli me seek-to-position-in-currently-playing-track — Seeks to the given position in the user’s currently playing track.
• spotify-pp-cli me set-repeat-mode-on-users-playback — Set the repeat mode for the user's playback. This API only works for users who have Spotify Premium.
• spotify-pp-cli me set-volume-for-users-playback — Set the volume for the user’s current playback device. This API only works for users who have Spotify Premium.
• spotify-pp-cli me skip-users-playback-to-next-track — Skips to next track in the user’s queue. This API only works for users who have Spotify Premium.
• spotify-pp-cli me skip-users-playback-to-previous-track — Skips to previous track in the user’s queue. This API only works for users who have Spotify Premium.
• spotify-pp-cli me start-a-users-playback — Start a new context or resume current playback on the user's active device.
• spotify-pp-cli me toggle-shuffle-for-users-playback — Toggle shuffle on or off for user’s playback. This API only works for users who have Spotify Premium.
• spotify-pp-cli me transfer-a-users-playback — Transfer playback to a new device and optionally begin playback. This API only works for users who have Spotify Premium.
• spotify-pp-cli me unfollow-artists-users — Remove the current user as a follower of one or more artists or other Spotify users.

playlists — Manage playlists

• spotify-pp-cli playlists change-details — Change a playlist's name and public/private state. (The user must, of course, own the playlist.)
• spotify-pp-cli playlists get — Get a playlist owned by a Spotify user.

recommendations — Manage recommendations

• spotify-pp-cli recommendations get — Recommendations are generated based on the available information for a given seed entity and matched against similar
• spotify-pp-cli recommendations get-genres — Retrieve a list of available genres seed parameter values for

shows — Manage shows

• spotify-pp-cli shows get-a — Get Spotify catalog information for a single show identified by its unique Spotify ID.
• spotify-pp-cli shows get-multiple — Get Spotify catalog information for several shows based on their Spotify IDs.

spotify_web_search — Manage spotify web search

• spotify-pp-cli spotify-web-search — Get Spotify catalog information about albums, artists, playlists, tracks, shows

tracks — Manage tracks

• spotify-pp-cli tracks get — Get Spotify catalog information for a single track identified by its unique Spotify ID.
• spotify-pp-cli tracks get-several — Get Spotify catalog information for multiple tracks based on their Spotify IDs.
• spotify-pp-cli tracks resolve — Resolve artist + title to exactly one track URI; reads a whole tracklist from stdin.
• spotify-pp-cli tracks where — Show every place a track appears in your library (playlists, saved, play history, top).

users — Manage users

• spotify-pp-cli users <user_id> — Get public profile information about a Spotify user.

Turning a tracklist into a playlist

/search answers with a ranked page, and its ranking is relevance, not title exactness — a live cut, a remaster, or a cover routinely outranks the studio recording you asked for. tracks resolve owns that re-ranking (exact title beats normalized-exact beats prefix; the requested artist always beats another artist) and emits one URI per input line, so a setlist becomes a playlist in three commands instead of one search per song plus hand-written jq:

# 1. Resolve the tracklist to URIs (one title per line on stdin).
pbpaste | spotify-pp-cli tracks resolve --artist Northlane --agent > resolved.json

# 2. Check what didn't resolve before creating anything.
jq -r '.results.results[] | select(.uri == null) | .query_title' resolved.json

# 3. Create the playlist and add the URIs.
PLAYLIST=$(spotify-pp-cli me create-playlist --name "Northlane / Milan" --agent \
  --select id | jq -r '.results.id')
spotify-pp-cli playlists items add-to-playlist "$PLAYLIST" --agent \
  --uris "$(jq -c '[.results.results[].uri | select(. != null)]' resolved.json)"

match_kind on each row says how the match was made (exact, normalized, prefix, substring, or *_other_artist when only a different artist's recording matched), so an agent can decide which rows need a human look. Add --fail-on-miss to exit 2 when any title fails to resolve.

Reading playlist contents: .item, not .track

playlists items get-playlists calls Spotify's /playlists/{id}/items endpoint, whose rows carry the track under item. Spotify's own documentation and most examples describe the older /playlists/{id}/tracks endpoint, whose rows use track — so a jq '.results.items[].track' copied from the docs silently returns null here. Use .item:

spotify-pp-cli playlists items get-playlists <playlist_id> --agent \
  | jq -r '.results.items[].item.name'

The playlists tracks ... subtree targets the legacy /tracks endpoint, which Spotify now answers with HTTP 403 for current app credentials. Prefer the playlists items ... subtree.

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

spotify-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.

Auth Setup

Run spotify-pp-cli auth setup for the URL and steps to obtain a token (add --launch to open the URL). Then store it:

spotify-pp-cli auth set-token YOUR_TOKEN_HERE

Or set SPOTIFY_OAUTH_2_0 as an environment variable.

Run spotify-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr. One deliberate exception: a --select that matches nothing writes its available_fields diagnostic into the normal envelope on stdout, since that list is data worth parsing, and prints a one-line explanation on stderr alongside it.

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Projection also descends through nested object envelopes (an object wrapping a single bounded collection) until it reaches the collection, so fields inside wrapped payloads are reachable without naming the envelope key. Critical for keeping context small on verbose APIs:

  spotify-pp-cli audio-analysis mock-value --agent --select id,name,status
  

  A --select that matches nothing is an error, not an empty result: the CLI exits 2 and returns a diagnostic naming the fields that were available, instead of falling back to the full payload. Paths are relative to the data, not to the {meta, results} envelope — write --select tracks.items.name, not --select results.tracks.items.name:

  spotify-pp-cli spotify-web-search --q "track:4D artist:Northlane" --type track \
    --json --select results.tracks.items.name
  # exit 2
  # {"results":{"error":"--select matched no fields","select":"results.tracks.items.name",
  #             "available_fields":["tracks","tracks.href","tracks.items", ...]}}
  

• Previewable — --dry-run shows the request without sending

• Offline-friendly — sync/search commands can use the local SQLite store when available

• Non-interactive — never prompts, every input is a flag

• Explicit retries — use --idempotent only when an already-existing create should count as success, and use --ignore-missing only when a missing delete target should count as success

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.

Envelope guarantees:

• The envelope is added exactly once, by the printer — never expect results to contain a second nested {meta, results} wrapper, and meta.source always reports the source the data actually came from.
• Commands that send a real POST/PUT/DELETE report source: "live" on every output path.
• Single-object endpoints (artists get-an, albums get-an, ...) return the whole resource in results, not a nested fragment of it.
• A multi-type live search that hits a per-type error keeps the types that succeeded and reports the incomplete result set in meta.reason — check meta.reason before treating a partial search as exhaustive.

Live search

search <query> hits Spotify's live /search endpoint, which requires a type parameter — the CLI resolves the requested types (all catalog types by default, or the one named with --type), sends them explicitly, and aggregates every populated per-type response. Types Spotify serves no live endpoint for (e.g. me, chapters) are local-only: asking for them with --data-source live fails fast with exit 2 and names the working alternatives (local or auto).

Paths and state

Agents should treat the CLI's path resolver as part of the runtime contract:

• Use --home <dir> for one invocation, or set SPOTIFY_HOME=<dir> to relocate all four path kinds under one root.

• Use per-kind env vars only when a specific kind must diverge: SPOTIFY_CONFIG_DIR, SPOTIFY_DATA_DIR, SPOTIFY_STATE_DIR, SPOTIFY_CACHE_DIR.

• Resolution order is per-kind env var, --home, SPOTIFY_HOME, XDG (XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME), then platform defaults.

• config contains settings like config.toml and profiles. data contains credentials.toml, data.db, cookies, and auth sidecars. state contains persisted queries, jobs, and teach.log. cache contains regenerable HTTP/cache files.

• Stored secrets live in credentials.toml under the data dir. Existing legacy config.toml secrets are read for compatibility and leave config.toml on the first auth write.

• Run spotify-pp-cli doctor --fail-on warn to surface path and credential-location warnings. agent-context exposes a schema v4 paths block for agents that need the resolved dirs.

• For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags:

  {
    "mcpServers": {
      "spotify": {
        "command": "spotify-pp-mcp",
        "env": {
          "SPOTIFY_HOME": "/srv/spotify"
        }
      }
    }
  }
  

Fleet precedence: an inherited per-kind env var overrides an explicit --home for that kind. Use SPOTIFY_HOME or per-kind vars as durable fleet levers, and use --home only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing SPOTIFY_HOME, or doctor will not find credentials left under the former root.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

spotify-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
spotify-pp-cli feedback --stdin < notes.txt
spotify-pp-cli feedback list --json --limit 10

Entries are stored locally as feedback.jsonl under the resolved data dir. They are never POSTed unless SPOTIFY_FEEDBACK_ENDPOINT is set AND either --send is passed or SPOTIFY_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled or recurring agent reuses the same saved flags while providing different input each run.

spotify-pp-cli profile save briefing --json
spotify-pp-cli --profile briefing audio-analysis mock-value
spotify-pp-cli profile list --json
spotify-pp-cli profile show briefing
spotify-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Exit Codes

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help → show spotify-pp-cli --help output
2. Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
3. Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:

claude mcp add spotify-pp-mcp -- spotify-pp-mcp

Verify: claude mcp list

Direct Use

1. Check if installed: which spotify-pp-cli If not found, offer to install (see Prerequisites at the top of this skill).
2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
3. Execute with the --agent flag:

   spotify-pp-cli <command> [subcommand] [args] --agent
   

4. If ambiguous, drill into subcommand help: spotify-pp-cli <command> --help.