✍️ I write about building tools like this at dubeykartikay.com.

Requirements

• A Spotify Premium account.
• A working system keyring.
• The patched lazyspotify-librespot daemon (only if you are installing from source or running an unpackaged build)
• On Linux, one of wl-clipboard, xclip, or xsel if you want clipboard support on the auth screen.

Install

Homebrew

brew tap dubeyKartikay/lazyspotify
brew install lazyspotify

Arch Linux

yay -S lazyspotify-bin

Nix

Available in Nixpkgs.

nix run nixpkgs#lazyspotify

GitHub Releases

Download the latest package from GitHub Releases.

• macOS: signed .zip
• Ubuntu/Debian: .deb
• Fedora/RHEL: .rpm
• Arch: .tar.gz

Example package installs:

sudo dpkg -i lazyspotify-*.deb
sudo dnf install ./lazyspotify-*.rpm

Build From Source

Build the app:

git clone https://github.com/dubeyKartikay/lazyspotify.git
cd lazyspotify
make build

Then build the patched daemon from dubeyKartikay/go-librespot and point librespot.daemon.cmd at that binary in your config.

If you build lazyspotify yourself and do not compile in a packaged daemon path, librespot.daemon.cmd is required.

Demos

Play A Track From Playlist > Track

Player Controls

Library Navigation

Search

Set Up Your Spotify Client ID

lazyspotify requires your own Spotify app client ID.

1. Open the Spotify Developer Dashboard.
2. Create a new app with:
   • App name: lazyspotify
   • App description: terminal based spotify client
   • Website: https://github.com/dubeyKartikay/lazyspotify
   • Redirect URIs: http://127.0.0.1:8287/callback
   • APIs used: Web API, Web Playback SDK
3. Copy the app's Client ID.
4. Put the Client ID in config.yml or export it as an environment variable. See Configuration.

Minimal config:

auth:
  client_id: your_spotify_app_client_id

Environment override:

export AUTH_CLIENT_ID=your_spotify_app_client_id

If you change auth.host, auth.port, or auth.redirect-endpoint, update the Spotify app Redirect URI to match exactly.

Configuration

Config file locations:

• macOS: ~/Library/Application Support/lazyspotify/config.yml
• Linux: ~/.config/lazyspotify/config.yml

If the file is missing, lazyspotify creates config.yml with:

auth:
  client_id: your_spotify_app_client_id

Then replace your_spotify_app_client_id with your Spotify app Client ID.

Minimal config for package installs:

auth:
  client_id: your_spotify_app_client_id

Minimal config for source or manual installs:

auth:
  client_id: your_spotify_app_client_id

librespot:
  daemon:
    cmd:
      - /absolute/path/to/lazyspotify-librespot

The generated daemon config is written automatically under the librespot/ subdirectory inside the app config directory. You usually do not need to edit it manually.

Auth Settings

Librespot Settings

Environment variables can override config values by replacing . and - with _. Examples: LOG_LEVEL, AUTH_CLIENT_ID, LIBRESPOT_DAEMON_LOG_LEVEL.

Run

Start the app with:

lazyspotify

If you built from source:

./target/lazyspotify

Print build metadata:

lazyspotify version

Development

make run
go test ./...

Community

• Code of Conduct
• Contributing Guide
• Security Policy