# musicli documentation

v0.2 · MIT License

##Overview

musicli is a Spotify player that runs entirely in your terminal. It renders album art, an audio visualizer, and gives you full playback control — no Electron, no browser, no GUI. Just your music and your terminal.

Requirements: Spotify Premium account, macOS (arm64 or x86_64) or Linux (x86_64).

##Installation

Install the prebuilt binary for your platform with one command:

curl -fsSL https://anirudlappathi.com/musicli/install.sh | bash

This downloads a binary for your OS/arch and installs it to ~/.local/bin. The installer will prompt you to add ~/.local/bin to your PATH if it is not already there.

###Update an existing install

musicli --update

Downloads and replaces the binary in-place. musicli also checks for updates automatically once per day on startup — see Auto-Update.

###Uninstall

rm ~/.local/bin/musicli
rm -rf ~/.config/musicli

##Setup

musicli requires a free Spotify Developer app to authenticate. This takes about 60 seconds. On first launch, a guided wizard walks you through every step.

###First-run wizard

1. 1.Create a Spotify app — the wizard opens developer.spotify.com/dashboard in your browser. Click Create app, give it any name, and click Create.
2. 2.Set the redirect URI — in your app's Settings, add this exact URI (the wizard copies it to your clipboard automatically):
   textcopy

   http://127.0.0.1:8888/callback

3. 3.Paste your Client ID — copy the Client ID from your app's dashboard and paste it into the wizard. It validates the format instantly.
4. 4.Authorize — a browser window opens to log in with Spotify. After authorizing, musicli starts. Your Client ID is saved to ~/.config/musicli/client_id and you won't see the wizard again.

Why your own app? Spotify's 2026 API changes limit each Developer app to 5 users. Instead of sharing one ID that would break for user #6, everyone creates their own — it's free and requires no approval.

###Environment variable override

Power users can skip the wizard entirely:

export SPOTIFY_CLIENT_ID="your_32_char_hex_id"

To reset and re-run the wizard:

musicli --reset

###Terminal recommendations

Album art rendering quality depends on your terminal's image protocol support:

##Features

###Now Playing

The left panel always shows what's playing: pixelated album cover art, track name, artist, progress bar, playback controls, and an audio visualizer. The visualizer gradient is derived from the current album's color palette. The entire UI accent color smoothly crossfades when the track changes.

###Multi-Type Search

Press S to open a search prompt. Results are organized into three sections — artists, albums, tracks — navigable with 1 2 3 jump keys. Press Enter on an artist to see their top tracks, or on an album to browse its tracklist.

###Library Browser

Browse your playlists, liked songs, queue, recently played, and top tracks. Every list supports fuzzy filtering (/), multi-field sorting (s), and virtual scrolling for instant navigation through thousands of tracks.

###Dynamic Theme

Colors are extracted from album cover art automatically. The visualizer gradient, accent colors, selection highlights, and UI elements all smoothly crossfade when the album changes. No configuration needed.

###Maximize Mode

Press m for a full-screen immersive visualizer. Six modes are available: Spectrum, Waves, Radial, Particles, Lissajous, Aurora. Cycle between them with v.

###Low Latency

Navigation (j/k/g/G) is sub-millisecond with no network calls. Playback controls use Spotify Connect — no Web API round-trip. All UI updates are optimistic; syncing happens in the background.

##Keybindings

Press z inside musicli to show the full interactive help overlay.

###Playback

###Views

###Navigation

###CLI Flags

##Configuration

Configuration is stored at ~/.config/musicli/config.toml and created with defaults on first run. Edit it with any text editor.

# ~/.config/musicli/config.toml

# How often to poll Spotify for playback state (milliseconds).
# Lower values give more responsive progress bars but use slightly more CPU.
poll_interval_ms = 5000

# Cache album art to disk to avoid re-fetching on every load.
# Cached images are stored in ~/.cache/musicli/covers/.
enable_cover_image_cache = true

Config file: ~/.config/musicli/config.toml
Client ID: ~/.config/musicli/client_id
Cover art cache: ~/.cache/musicli/covers/

##Auto-Update

musicli checks for a newer release once per day on startup. If a newer version is available, the status bar shows:

Update available: v0.2.0 (run musicli --update)

Run musicli --update to download the new binary and replace the current one in-place. Your config and credentials are not affected.

musicli --version

##How It Works

musicli connects to Spotify in two independent ways:

• ✦Spotify Web API — browsing, search, library management, and reading playback state. All calls are non-blocking and run in a background thread.
• ✦Spotify Connect — musicli registers as a Connect device. Play, pause, skip, seek, and volume go directly through the Connect layer with no Web API round-trip, giving near-instant response.

Album art colors are extracted using a median-cut quantization algorithm. The dominant palette drives the visualizer gradient and UI accent color, which crossfade smoothly on every track change.