pp-spotify

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/media-and-entertainment/spotify/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# 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:
   ```bash
   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.3 or newer):

```bash
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.

## When to Use This CLI

Reach for spotify-pp-cli when an agent needs to read or steer a user's Spotify session, curate playlists, or answer questions about their listening history. It is the right choice over generic HTTP calls when the task benefits from the local SQLite store (drift queries, snapshot-aware playlist diffs, extended play history past the 50-event cap) or from the deprecation-aware stubs that route around endpoints Spotify removed for new apps. Prefer it over spotify-tui when the workflow is one-shot rather than interactive, and over spotipy when the host is an agent rather than a Python script.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Playlist maintenance
- **`playlists diff`** — Compare a playlist's current state against any prior snapshot to see exactly which tracks were added, removed, or reordered.

  _Reach for this when a user asks 'what changed in this playlist?' or wants to undo an algorithmic refresh on a collab playlist._

  ```bash
  spotify-pp-cli playlists diff 37i9dQZF1DXcBWIGoYBM5M --against-snapshot abc123 --agent
  ```
- **`playlists dedupe`** — Find duplicate tracks in a playlist by ISRC (catches the album/single/EP/deluxe-reissue dupe class), report by default, --apply to remove.

  _Use this when a curator's playlist has the same recording on three different albums; Spotify's app treats them as distinct._

  ```bash
  spotify-pp-cli playlists dedupe 37i9dQZF1DXcBWIGoYBM5M --by isrc --agent
  ```
- **`playlists merge`** — Combine multiple playlists into one with built-in dedupe and ordering controls.

  _Reach for this when a DJ wants to consolidate retired set playlists into a deep-archive without manually de-duplicating._

  ```bash
  spotify-pp-cli playlists merge 37i9dQZF1DXcBWIGoYBM5M 37i9dQZF1DX0XUsuxWHRQd 6rqhFgbbKwnb9MLmUQDhG6 --into <new-playlist-id> --dedupe-by isrc --order by-date
  ```

### Listening drift
- **`top drift`** — Compare two top-tracks snapshots and show who rose, fell, or stayed stable across a time window.

  _Use this when a user asks 'which artists fell off my top-50 between Q1 and Q4?' or wants to track their own listening identity over time._

  ```bash
  spotify-pp-cli top drift --range medium --since 2026-01-01 --agent --select risen,fallen,stable
  ```
- **`releases since`** — List new albums and singles released since a date by artists you follow, sorted newest first.

  _Reach for this when a user asks 'what's new from artists I follow' and the deprecated Release Radar is no longer reachable._

  ```bash
  spotify-pp-cli releases since 2026-05-01 --from followed --agent --select name,artists.0.name,release_date
  ```
- **`play history`** — Bucket your recent play history by the playlist or album that drove each play, ranked by play count and total duration.

  _Reach for this when a DJ asks 'which of my set lists is actually getting played this week' or when a journalist wants column data on listening patterns._

  ```bash
  spotify-pp-cli play history --by context --since 7d --agent --select context_name,play_count,total_duration_min
  ```

### Cross-collection lookup
- **`tracks where`** — For a given track, find every place it appears in your data: which playlists, whether saved, last played, and on which devices.

  _Use this before adding a track to a playlist to avoid duping it, or to answer 'have I played this before' questions._

  ```bash
  spotify-pp-cli tracks where 4uLU6hMCjMI75M1A2tKUQC --agent
  ```

### Agent-native playback
- **`queue from-saved`** — Pick the N most recently saved tracks from your library and queue them in one command.

  _Use this when an agent should "queue 10 more from my saved tracks" without resorting to URI manipulation. Per-artist and per-playlist filters are not yet implemented; the saved_tracks schema does not carry artist or playlist linkage and adding it requires a join against a tracks-cache table._

  ```bash
  spotify-pp-cli queue from-saved --limit 10
  ```
- **`play-on`** — Start playback on a device referenced by friendly name (e.g. "family room") instead of opaque device IDs. Resolves against both the live `/me/player/devices` list and the locally cached `devices_seen` table populated by `sync-extras`.

  _Reach for this when an agent says "play X on the kitchen speaker" or "send this to my office" — Spotify's API only takes opaque device IDs, so users normally have to list devices and copy/paste; play-on closes that loop with a name index. Cached entries let you reference devices that aren't currently online (with a typed "wake the device first" hint instead of a raw 404). Name matching is case-insensitive, exact > prefix > substring; ambiguous matches list the candidates._

  ```bash
  spotify-pp-cli play-on "family room" --uris '["spotify:track:0nys6GusuHnjSYLW0PYYb7"]'
  spotify-pp-cli play-on iphone --context-uri spotify:album:1ER3B6zev5JEAaqhnyyfbf
  ```

### Music discovery
- **`discover artists`** — Find artists you don't follow yet who match the genres of your top, saved, or followed artists, ranked by popularity within each genre.

  _Reach for this when the user asks 'find me new artists like the ones I already listen to' and the deprecated recommendations endpoint isn't an option._

  ```bash
  spotify-pp-cli discover artists --seed top --exclude-followed --limit 25 --agent --select name,genres,popularity,top_track.name
  ```
- **`discover via-playlists`** — Find artists frequently co-curated with a seed artist by searching public playlists that contain them and ranking other artists by co-occurrence count.

  _Use this for the 'who sounds like X' question Spotify used to answer with related-artists; curator-driven co-occurrence is often a better signal anyway._

  ```bash
  spotify-pp-cli discover via-playlists 0OdUWJ0sBjDrqHygGUXeCF --min-cooccurrence 5 --limit 20 --agent
  ```
- **`discover artist-gaps`** — For an artist, show their full discography chronologically with each album marked as saved or unsaved against your library.

  _Reach for this when a user says 'I love this artist, what have I missed?' — surfaces the gap in their own collection._

  ```bash
  spotify-pp-cli discover artist-gaps 0OdUWJ0sBjDrqHygGUXeCF --show unsaved --include-groups album,single
  ```
- **`discover new-releases`** — Filter Spotify's global new-releases feed down to releases whose artists share a genre with your top or followed artists; optionally exclude artists you already follow.

  _Use this for 'what new music came out this week in genres I actually lis