Setup guide

Create a Spotify Developer app

Spotify Premium is required to create a developer app (this can't be checked automatically — it's a hard prerequisite). Go to the Spotify Developer dashboard and create an app.

Use exactly this redirect URI — LikedZero's local login server listens here:

http://127.0.0.1:8888/callback

Note the Client ID shown on the app page — you'll need it in step 3. No Client Secret is needed.

Fork the repository

Fork github.com/Vishnu-DRX/LikedZero to your own GitHub account, then clone your fork locally.

git clone https://github.com/<your-username>/LikedZero.git

Get your refresh token locally

Install Python 3.12, then from inside your cloned fork:

python -m pip install -r requirements.txt

Copy .env.example to .env and put your Client ID from step 1 in it:

SPOTIFY_CLIENT_ID=your-client-id-here

Then run the one-time login:

python -m src.spotify_client --setup

This opens your browser to Spotify's own login screen, then captures the result on 127.0.0.1:8888. Nothing secret is printed to the terminal.

Add the two Actions secrets

LikedZero's scheduled workflow needs SPOTIFY_CLIENT_ID and SPOTIFY_REFRESH_TOKEN as GitHub Actions secrets on your fork. Never paste these into this website — only into GitHub itself.

Windows:

powershell scripts/set_secrets.ps1

macOS / Linux (values are piped in via stdin, never shown or logged):

gh secret set SPOTIFY_CLIENT_ID --body "$SPOTIFY_CLIENT_ID"
gh secret set SPOTIFY_REFRESH_TOKEN --body "$SPOTIFY_REFRESH_TOKEN"

Enable Actions, allow it to write, and enable Pages

GitHub disables Actions on every new fork. In your fork's Actions tab, click "I understand my workflows, go ahead and enable them" — without this, the Sync workflow cannot run at all, even manually.

Then: Settings → Actions → General → Workflow permissions, select Read and write permissions, and save. This lets a run commit its own logs back to your repo.

Then: Settings → Pages, set source to Deploy from a branch, branch main, folder /docs.

Create your config

Open Configure on your Pages site and build your rules. Either click Save to GitHub to commit config.yaml straight to your fork (it walks you through connecting a token, scoped to just this repo — the same token also covers the Dashboard's Run now button, so you only connect once), or click Save configuration and put the downloaded file in your repo's root yourself.

First dry run

Either use the Run now button on your Dashboard's Overview (if you already connected a token via Save to GitHub, it's ready immediately — the same token covers both), or go to GitHub: Actions → Sync → Run workflow, leave dry run ticked, and run it. Then open the Dashboard and read the Overview and Inbox views.

Go live, later

When the dry run looks right, live runs are still guarded: a newest N selector and a max-moves cap stop any single run from touching more than you expect. There is no schedule until you turn one on: in Configure, open Run automatically, pick a time in your own timezone and save. Scheduled runs are dry runs until you also switch on Really move songs on schedule, which needs an inbox_since date so an unattended run can never reach your old library.

By default, committed run logs hide song titles (logging.include_track_names: false) — public logs carry counts and decisions only, with no song-identifying links (a bare Spotify URI resolves to a real song in one request, so those are stripped too). Turn it on in Configure if you want your own logs to show titles, or open the log files locally in the dashboard to see titles regardless of this setting.