spotme

A small command-line tool for managing my Spotify library and playback — find unavailable or duplicate tracks in your liked songs, control playback, and see what's playing.

Built on spotipy.

Requirements

• Python 3.10+
• A Spotify developer app (client ID + secret)
• Spotify Premium (required by Spotify for playback control)

Setup

Install from PyPI with pipx (recommended):

pipx install spotme-cli

It's published as spotme-cli because the plain spotme name was already taken on PyPI — the command you run is still spotme.

To install from a local checkout instead:

pipx install .

Or set up a development environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Credentials

The quickest way is to run the setup command and answer the prompts:

spotme init

That writes ~/.config/spotme/.env for you. To do it manually, copy the example config and add your keys from the Spotify developer dashboard:

mkdir -p ~/.config/spotme
cp .env.example ~/.config/spotme/.env

Fill in SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET. Keep SPOTIPY_REDIRECT_URI as http://127.0.0.1:8888/callback, and make sure that URI is added to your app's redirect URIs in the Spotify dashboard.

A .env in the current directory also works and takes precedence — handy while developing.

Usage

spotme <command>

From a repo checkout without installing, python -m spotme <command> works too.

The first command you run opens a browser window for OAuth login; tokens are cached at ~/.cache/spotme/token.

Library commands (unavailable, duplicates) page through all of your liked songs and can take a moment on large libraries. Playback commands (play, pause, next, playing) require an active Spotify device.

start shows a numbered list of your available devices to pick from, plus a browser option at the end. Choosing browser opens the Spotify web player, waits for it to register as a new device, then starts playback there. Note that browser autoplay policies may require one manual click in the tab before the first remote play goes through. Any Spotify Connect device (e.g. the desktop app or a headless daemon like spotifyd) shows up in the list automatically. Enter nothing or q to cancel.

Testing

Tests use pytest and mock the Spotify API — no credentials or network needed:

pip install -e '.[dev]'
python -m pytest