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.

Command Description
init set up spotify credentials
playing show what's currently playing
start launch spotify and start playback
play start playback
pause pause playback
next skip to the next track
devices list available devices
activate transfer playback to the computer
unavailable find unavailable tracks in liked songs
duplicates find duplicate tracks in liked songs

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

Project links

Data verified by PyPI on Aug 24, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nealwp from gravatar.com nealwp

Credits

Author: nealwp

GitHub Statistics

Data verified by PyPI on Aug 24, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev

Tags

spotify cli music

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

spotme_cli-0.1.1.tar.gz (14.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

spotme_cli-0.1.1-py3-none-any.whl (9.5 kB view details)

Uploaded Python 3

File details

Details for the file spotme_cli-0.1.1.tar.gz.

File metadata

  • Download URL: spotme_cli-0.1.1.tar.gz
  • Upload date:
  • Size: 14.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for spotme_cli-0.1.1.tar.gz
Algorithm Hash digest
SHA256 85d5351a1eaf0704cffa8f2e6cadfe333bbd0e487c918a9073d20cd9d7a7743e
MD5 36bc175e8058ae54defcad70e1f170c1
BLAKE2b-256 63f94aa45b72bd9d4f348fce528c8c896b679e4f76c14be1f646f6b485123769

See more details on using hashes here.

Provenance

The following attestation bundles were made for spotme_cli-0.1.1.tar.gz:

Publisher: publish.yml on nealwp/spotme

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file spotme_cli-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: spotme_cli-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 9.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for spotme_cli-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 57ad0342be32b35621de65fea46a468ceb062b69981ea579371d43c3210fcdc2
MD5 3821fde066ea1a5d2e33bcc53259097e
BLAKE2b-256 67237a883adca54e1c6b127653e9ad06474bcf7565261cb7e160d4ab7e863f5f

See more details on using hashes here.

Provenance

The following attestation bundles were made for spotme_cli-0.1.1-py3-none-any.whl:

Publisher: publish.yml on nealwp/spotme

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page