Follow-up to v0.6.0 fixing three bugs that only manifest on Development Mode apps created after 2026-02-11 (Carla's case):

• `spoti-cli search` crashed with TypeError when the `genres` field is missing from Artist responses. Now defensive across every optional field.
• `search --limit 20` returned 400 Invalid limit — Spotify dropped the cap from 50 to 10. CLI now caps silently.
• `spoti-cli artist top-tracks` returned 403 — `/artists/{id}/top-tracks` was removed in Feb 2026. CLI now falls back to `/search?type=track` filtered by artist id, returning real top tracks.

`recommend` also got the same limit cap and defensive coding.

Upgrade

```bash
bun add -g @crafter/spoti-cli@latest
```

Fixes #2.

Spotify shipped breaking Web API changes that hard-deprecated the endpoints spoti-cli was using for every write/library call. Apps created after 2026-02-11 lost access immediately; existing apps follow once Spotify lifts the postponed shutdown.

If you were getting 403 Forbidden on create, playlist add, library save/remove/check — this is the fix.

Endpoint migration

Note that /me/library writes/deletes take a query-param URI list, not a body. Counterintuitive but verified empirically.

playlist list was also reading p.tracks.total, which broke. Now reads either items.total or tracks.total for back-compat.

Better 403 / 404 messages

The previous 403 message always blamed Development Mode allowlist. Now it lists the three real causes in order of likelihood:

1. Endpoint deprecated — suggests npm i -g @crafter/spoti-cli first
2. App in Development Mode without User Management
3. Redirect URI mismatch in the dashboard (localhost ≠ 127.0.0.1, https ≠ http, trailing slash, etc.)

Onboarding text now flags the redirect-URI byte-exact requirement and the post-Feb-11 Premium + 5-user app limit up front.

Upgrade

bun add -g @crafter/spoti-cli@latest
# or
npm i -g @crafter/spoti-cli@latest

No re-auth needed if you already have a token. Just upgrade and retry.

Big thanks to @rockscafe for the meticulously-documented issue.

Three playlist-related fixes Hunter hit while building voice control:

• fix(create): newly created playlists are now followed automatically so they appear in me/playlists (was a Spotify Web API quirk where create-via-API doesn't auto-follow). Pass --no-follow to opt out.
• feat(search): -t playlist now supported (was missing — only track/artist/album worked before).
• feat(playlist list): new --filter <regex>, new --mine (only your owned playlists), and proper pagination beyond the 50-per-page Web API cap (use --limit up to 500).

PR #1.

Breaking-ish

auth now grants the full scope set on first run (playback, library, top, history, playlist read+write). Existing tokens from v0.3.x still work but are missing playlist-read-private — re-run spoti-cli auth to refresh.

Fixes

• playlist list no longer returns 403 Insufficient client scope on a fresh auth (added playlist-read-private + playlist-read-collaborative to the default scopes).
• 403/401/429 errors now print actionable next steps:
  • 403 + Insufficient client scope → suggests spoti-cli auth
  • 403 + Forbidden → explains Development Mode and how to add yourself as a test user in the Spotify dashboard
  • 401 → suggests re-auth
  • 429 → wait and retry
• After auth, the CLI prints the two most common first-run gotchas so users know what to do if a 403 hits.
• --upgrade is now a deprecated noop — auth always grants every scope.

Changes

• Guided onboarding for spoti-cli auth — runs without a client-id now prints a colored step-by-step checklist with the exact dashboard URL, redirect URI (http://127.0.0.1:8888/callback), and Web API checkbox. No more guessing.

Agents can paste the printed steps directly to users instead of repeating them from memory.

What's New

spoti-cli goes from 8 to 22 commands with full Spotify control.

Playback Control (10 commands)

player now, play, pause, next, prev, queue, devices, volume, shuffle, repeat

Personalization (3 commands)

top tracks, top artists, history -- with time range support (4 weeks / 6 months / all time)

Library Management (4 commands)

library list, save, remove, check

Track & Artist Info (5 commands)

track get, track features, artist get, artist top-tracks, artist albums

Infrastructure

• Lazy scope upgrade: existing users keep working, auth --upgrade adds new permissions when needed
• Non-JSON response handling: player endpoints no longer crash on empty responses
• Device fallback: auto-selects first available device when no active device found
• Premium detection: graceful error for Premium-only endpoints

Install

bun add -g @crafter/spoti-cli

Upgrade scopes for new commands:

spoti-cli auth --upgrade

v0.2.1 — Patch Release

Bug fix for non-JSON response handling in player endpoints.

Fix

• Player endpoints (play, pause, next, prev) no longer crash when Spotify returns non-JSON responses

Install

```bash
bun add -g @crafter/[email protected]
```

Note: v0.3.0 is the recommended version with all new commands.