Perfect Playlist

---
name: perfect-playlist
description: Build, append, verify, export, search, and inspect exact Spotify playlists with the Perfect Playlist CLI. Use when a user asks to create a Spotify playlist from named songs or exact Spotify references, fill an owned empty playlist, append exact tracks, compare playlist order and contents, export a durable track Source, or discover and confirm Spotify track candidates without substitutions.
---

# Perfect Playlist

Use Perfect Playlist as a deterministic final-mile tool. Discovery may interpret
a user's request, but every write must receive the exact ordered Spotify track
references selected for that request.

## Preserve the safety boundary

- Use Search and Inspect for discovery; neither command chooses tracks or writes
  a playlist.
- Resolve every requested song to one inspected canonical Spotify track URI
  before any write. Never pass natural-language candidates to Build or Add.
- Preserve the user's order and duplicates. Never substitute, reorder, dedupe,
  or silently skip unavailable or invalid tracks.
- Build only a new public playlist or an owned empty public/private target.
- Use Add only for an explicit append request against a verified writable target.
  Add never changes visibility or earlier tracks.
- Never overwrite, repair, insert into, or generatively modify a playlist.
- Do not automatically retry Build or Add after a partial or unverified failure;
  a retry could duplicate tracks. Report the playlist URL and failure instead.

## Run the preflight

1. Run `perfect-playlist --help`. If the command is missing, install Python 3.11+
   and run `python -m pip install perfect-playlist` only when the user has
   authorized that software change. Then rerun `perfect-playlist --help`.
2. Run `perfect-playlist auth status` before Spotify-backed discovery or writes.
3. If configuration is missing, have the user set `SPOTIPY_CLIENT_ID`,
   `SPOTIPY_CLIENT_SECRET`, and `SPOTIPY_REDIRECT_URI` locally, or place them in
   an external environment file and set `PERFECT_PLAYLIST_SECRETS_FILE` to its
   path. Do not ask the user to paste secret values into the conversation.
4. Use `perfect-playlist auth login` for interactive authorization, then rerun
   `auth status`.

Never open, print, copy, commit, or expose an existing secrets file, OAuth code,
token cache, or credential value. Run separate CLI processes serially when they
share the same OAuth cache.

## Discover exact tracks

For each requested song, in the user's order:

1. Run `perfect-playlist search QUERY --json`; use `--limit 1..10` when the
   default four candidates are insufficient.
2. Compare title, artists, explicit status, duration, URI, and Spotify link with
   the request.
3. Run `perfect-playlist inspect TRACK_URI_OR_URL --json` on the intended result.
4. Record the canonical `spotify:track:<id>` URI returned by Inspect.

Treat an exact title-and-artist request as the caller's song choice, but do not
guess among live, remastered, clean, explicit, sped-up, slowed, re-recorded, or
otherwise plausible versions. Present ambiguous candidates and wait for the
user to choose. If no exact candidate is available, stop and report that track;
never choose a similar song.

## Create a durable Source

Create a new local YAML, JSON, or text Source containing only the inspected
tracks. Do not overwrite an existing Source without explicit permission. YAML
and JSON use a top-level `tracks` array; text uses one URI or typed Spotify track
URL per nonblank line and may contain `#` comments.

```yaml
tracks:
  - spotify:track:354WZaV3u6cuzTG2PmpYwm
  - spotify:track:78APbsosmvDYIwZHjzC5ZE
```

Prefer canonical track URIs. Typed `open.spotify.com/track/...` URLs are also
accepted and normalized. Raw 22-character IDs, stdin (`-`), arbitrary remote
documents, playlist metadata, names, targets, and privacy settings do not belong
in a TrackSequence. Invalid entries fail the entire Source.

## Choose one write workflow

- New public playlist with default settings:
  `perfect-playlist build SOURCE`
- New public playlist with an exact case-sensitive name:
  `perfect-playlist build SOURCE --name "NAME"`
- Owned empty public target:
  `perfect-playlist build SOURCE --target PLAYLIST_URI_OR_URL`
- Owned empty private target:
  `perfect-playlist build SOURCE --private --target PLAYLIST_URI_OR_URL`
- Explicit append to an owned or collaborative writable target:
  `perfect-playlist add SOURCE --target PLAYLIST_URI_OR_URL`

With no `--name` or `--target`, Build creates a new public `My Perfect Playlist`
and advances through numeric suffixes when needed. An explicit name collision
fails instead of changing the name. Perfect Playlist does not create a new
private playlist: ask the user for an owned empty private target. Never use a
collaborative playlist as a Build target.

## Verify and report

Build and Add validate before writing and read back Spotify state afterward.
After a successful write, also run
`perfect-playlist verify SOURCE PLAYLIST_URI_OR_URL` for an explicit peer
comparison when the playlist must exactly equal the Source. For Add, this full
comparison is appropriate only when the target was empty before the append;
otherwise rely on Add's verified appended-segment result.

Interpret exit codes exactly:

- `0`: success, or exact equality for Verify.
- `1`: two valid Verify Sources differ in count or first differing position.
- `2`: handled input, filesystem, authentication, Spotify, safety, or
  partial-write failure.

Report the durable Source path, playlist name and URL, requested visibility or
target mode, exact track count, and verification outcome. Surface failures
verbatim enough to preserve their actionable detail. Do not claim success from
a playlist URL alone, and do not delete or unfollow a result unless the user
explicitly asks.

## Use read-only workflows when appropriate

- Compare any two Sources with `perfect-playlist verify LEFT RIGHT`.
- Print canonical URI lines with `perfect-playlist export SOURCE`.
- Write a new `.yaml`, `.yml`, `.json`, or `.txt` file with
  `perfect-playlist export SOURCE --out NEW_PATH`.
- Render text-only Spotify links with `perfect-playlist export SOURCE --links`.

Export never overwrites an existing file. Search and Inspect JSON responses are
command data for discovery, not portable Sources.