I wrote a proper setup guide for setlisted, my Spotify CLI for headless boxes, and made GitHub run the guide's steps on a fresh machine every week. The first run found a bug I'd shipped and never seen.

The bug

setlisted can read credentials from an optional secrets backend. I always have that backend, so I never ran it without one. On a fresh clone you don't, and the line that catches errors named the backend's error class. With the backend missing, that name doesn't exist, so instead of this:

error: SPOTIFY_CLIENT_ID is not set. Put it in the environment or ~/.spotify-dj.env (see README).

you got a Python traceback ending in AttributeError: 'NoneType' object has no attribute 'SecretError'. Every single error, for every new user, looked like a crash. Fixed now, and the weekly check asserts the clean message, exit code 1 and no traceback.

What the check proves

The setup check passing: offline tests, every subcommand's help, and the clean missing-credential error

It installs from a fresh clone, runs the offline sequencer tests, loads --help for all 17 subcommands and checks that missing-credential error. It never talks to Spotify: no credentials in CI, and the quota is real.

The setup, short version

You need Python 3.10+, a Spotify account (Premium for playback) and a free Spotify app.

git clone https://github.com/casareanderson/setlisted && cd setlisted python3 -m pip install -r requirements.txt python3 tests/test_sequence.py # ALL OFFLINE TESTS PASS

In the Spotify dashboard, create an app, tick Web API and set the redirect URI to exactly http://127.0.0.1:8888/callback. Put the client id and secret in ~/.spotify-dj.env, then:

python3 spotify_dj.py auth-url # open it, approve, copy the dead 127.0.0.1 URL python3 spotify_dj.py auth-exchange "http://127.0.0.1:8888/callback?code=..." python3 spotify_dj.py devices # success: your Spotify Connect devices

setlisted sequence --help output

The full guide, with every setting and every error message the code prints, is docs/SETUP.md. The one I'd read first: Spotify answers 403, not 404, for endpoints it removed in February 2026, so a renamed path looks like a permissions problem.

Has a guide you wrote ever found a bug in your own code? It's a bit humbling tbh.

🤖 Drafted with AI assistance from my own homelab notes, logs and repos, then reviewed and edited before publishing.