Spotify Playlist CLI

Version 4.0.0 is the fourth iteration of the product. This implementation was rebuilt from scratch from the cognitive context in ctx/ and not restored from historical code.

This version was created by agent Codex GPT-5.4 with reasoning level Low, follows TeqFW platform rules, and is verified with unit and integration tests.

What The Product Does

• reads one plain-text track list file
• resolves tracks through Spotify Web API search
• selects one match by exact artist, exact track name, and earliest release preference
• removes duplicate Spotify track ids before playlist insertion
• creates one new playlist per normal run
• supports --dry-run without mutating the Spotify account
• supports --web-server mode for OAuth callback handling

Requirements

• Node.js >= 20
• npm
• a Spotify application configured for Authorization Code Flow
• a registered redirect URI for the callback endpoint

Installation

npm install

Runtime Configuration

Supported variables:

• SPOTIFY_CLIENT_ID
• SPOTIFY_CLIENT_SECRET
• SPOTIFY_REDIRECT_URI
• SPOTIFY_CALLBACK_PORT
• SPOTIFY_TOKEN_FILE

If SPOTIFY_TOKEN_FILE is omitted, the default path is var/spotify/oauth.json.

If a root-level .env file exists, version 4.0.0 loads it automatically during startup before runtime configuration is frozen.

Run Modes

npm start -- ./tracks.txt "Road Trip"
npm start -- ./tracks.txt "Road Trip" --dry-run
npm start -- --web-server

Equivalent executable forms:

create-playlist <file> <playlistName>
create-playlist <file> <playlistName> --dry-run
create-playlist --web-server

Input Format

Each content line must use:

<index>. <artist> — <track name>

Notes:

• numbering is optional
• the separator is the em dash —
• empty lines are ignored
• lines starting with # are ignored

Testing

npm test
npm run test:unit
npm run test:integration
teqfw-esm-validator src

The current v4 codebase is covered by:

• TeqFW unit tests with one test file per testable source module
• scenario-oriented integration tests for file mode, dry-run mode, OAuth callback handling, and long-running web-server mode
• teqfw-esm-validator verification for src/

Scope Limits

• one search request per declaration
• no fuzzy matching or fallback queries
• no automatic token refresh
• no caching, retries, or rate-limit recovery