# musicli documentation

v1.1.0 · MIT License

##Overview

musicli is Spotify on your computer, in the terminal or in a window. It is two apps that share a name and a style, both written in Rust:

• ✦The terminal app (musicli) — album art, visualizers, lyrics and full playback control in your terminal. It plays music right on this computer, so it works as a complete Spotify player: search, your library, playlists, albums, artists, queue, devices, radio and autoplay.
• ✦The desktop app (musicli.app) — your library, search, queue and playback in a native window. It starts in well under a second, has no browser inside, and needs just one sign-in with your Spotify account.

Requirements: Spotify Premium to play music (without Premium the terminal app still works as a remote for your other devices). Terminal app: macOS (arm64 or x86_64) or Linux (x86_64). Desktop app: macOS.

###New in v1.1.0

• +A Spotify-style layout: Your Library, the page and Now Playing side by side, with a player bar
• +Classic view (V) keeps the earlier one-page-at-a-time layout
• +Plays music on this computer, not only as a remote: queue, radio, autoplay and devices
• +Home, artist pages, profiles, Friend Activity, lyrics, mouse support and a command palette
• +9 full-screen visualizers that follow the beat you hear
• +The new musicli desktop app for macOS

##Installation

###Terminal app

Install the prebuilt binary for your platform with one command:

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

This downloads the binary for your OS and architecture and installs it to ~/.local/bin (set MUSICLI_INSTALL_DIR to change it). The installer tells you to add ~/.local/bin to your PATH if it is not there yet.

Building on Linux needs the ALSA and D-Bus headers: sudo apt-get install -y libasound2-dev libdbus-1-dev pkg-config

###Desktop app (macOS)

Download musicli-app-darwin-aarch64.zip (Apple Silicon) or musicli-app-darwin-x86_64.zip (Intel) from the releases page, unzip it and drag musicli.app to Applications. The app is not signed for distribution, so the first time right-click it and choose Open, or run:

xattr -dr com.apple.quarantine /Applications/musicli.app

###Uninstall

rm ~/.local/bin/musicli
# macOS
rm -rf ~/Library/Application\ Support/musicli ~/Library/Caches/musicli
rm -rf /Applications/musicli.app
# Linux
rm -rf ~/.config/musicli ~/.local/state/musicli ~/.cache/musicli

##Setup

Want a look first? musicli --demo runs the whole terminal app on sample music, with no account and no internet.

###Terminal app: first run

The terminal app talks to Spotify through a free personal Spotify app on your account. On first start it walks you through creating one and approving playback, in five short cards (about two minutes):

1. 1.Create the app. Press o to open developer.spotify.com/dashboard. Click Create app and name it anything.
2. 2.Add the Redirect URI. Paste this address under Redirect URIs (press c to copy it), tick the Web API box, accept the terms and save:
   textcopy

   http://127.0.0.1:8888/callback

3. 3.Paste your Client ID from the app's page. musicli checks it before going on.
4. 4.Approve musicli in the browser that opens. On another computer, paste the address the browser ended up on instead.
5. 5.Approve playback on this computer. Spotify needs a separate approval to play music here, so your browser opens once more. Not now (esc) skips it; musicli then controls your other devices until you approve.

Whenever a sign-in or approval is missing, the top bar shows [ ^L Log in ]. You can redo any of this later in Settings (,) → Personal Spotify app. Listening with a second Spotify account? Add it under User Management on your app's dashboard page.

Already using musicli? Your saved Client ID and sign-in keep working, and your files move to their new folders once, on the first start. Playing music on this computer needs one new approval (the Approve playback on this computer card, or ^L later).

###Desktop app: sign in

The first start shows one button, Sign in with Spotify. Signing in is one approval in your browser — no developer app to create and nothing to copy or paste. The sign-in is kept in your Keychain, so the browser is not needed again until you sign out. Behind a proxy? The sign-in card has Proxy Settings.

###Terminal recommendations

For the sharpest album art, use a terminal that can show images. Other terminals draw the art with coloured half-blocks, which still look good at a lower resolution.

##Features

Everything below is the terminal app.

###Spotify-style layout

Your Library on the left, the page in the middle and Now Playing on the right, with a player bar along the bottom. On narrow terminals the side panes become drawers. { and } show or hide them, Tab moves between them, and [ / ] go back and forward. Press V for the Classic view, the earlier one-page-at-a-time layout.

###Now Playing & dynamic colour

Pixelated album art, track info and controls. The whole app takes its colours from the album and fades to the next album's colours when it changes.

###Home

H opens shelves of what you played lately, mixes made for you, your top tracks and artists, your playlists and saved albums. It shows up at once and updates by itself.

###Search

S searches. Your library answers as you type; Spotify's results follow a moment later, laid out like Spotify: a top result card, songs, then artists, albums and playlists as cover tiles. Number keys jump between sections.

###Your Library & long lists

Playlists (with your folders), saved albums, followed artists and podcasts, with Liked Songs pinned first. A playlist with thousands of songs opens at its full length at once; songs still on their way show as placeholder rows and fill in by themselves.

###Artists, albums & profiles

Artist pages laid out like Spotify's: popular songs, discography, similar artists and About. M opens your profile; profiles show playlists, followers and who they follow.

###Friend Activity

W shows what the people you follow are listening to, in the right panel. ⏎ plays a song where they played it from.

###Queue, radio & autoplay

One queue list that follows every track change. a queues a song or a whole album or playlist, R starts radio, and with autoplay on (o) the music never just stops. The queue comes back after a relaunch.

###Lyrics

w shows lyrics in a panel on the right; the current line is highlighted and followed. From Spotify, with LRCLIB as the fallback.

###Maximize mode

m opens a full-screen visualizer with 9 looks, cycled with v: Spectrum, Mirror, Nebula, Aurora, Galaxy, Aurora Storm, Supernova, Deep Field and Kaleidoscope. Each beat peaks on screen within a few milliseconds of when you hear it. f turns on Focus: only the visualizer.

###Mouse & command palette

Everything you can do with the keys you can do with the mouse: click to open, double-click to play, right-click for a menu, drag to seek. ^K (or ⌘K) opens a fuzzy command palette over every action, playlist, album and artist.

###Extras

Media keys and system media controls, track notifications, a sleep timer, an idle screensaver, a now-playing line for tmux, and optional Discord status and Last.fm scrobbling under Settings → Advanced.

##Desktop App

The desktop app gives you playback, the queue, devices, your playlists and folders, albums, artist pages, podcasts, radio, autoplay and lyrics in a native window.

###Control it from the command line

The same program controls a running musicli, for scripts and keyboard shortcuts:

alias musicli-app=/Applications/musicli.app/Contents/MacOS/musicli-app
musicli-app play-pause
musicli-app next
musicli-app volume 40
musicli-app now-playing
musicli-app check-spotify   # which features Spotify answers for your account

Some features (Liked Songs, saved albums, like buttons, song search, playlist editing, Home) rest on private Spotify services that can change; when one stops working the app hides it instead of showing an error. Spotify's own Home, top songs and artists, and reordering playlists are not available.

##Keybindings

Press ? inside musicli for the full list (type to search it). Hints at the bottom of the screen show the keys for what you are looking at.

###Most used

###Playback

###Views

###Navigation

###Tracks & playlists

##Command Line

Something not working? Start with musicli --debug: error messages say exactly what went wrong (^Y copies them) and e opens a page with everything musicli noticed.

##Configuration

Settings (,) changes everything that can change while musicli runs. The rest lives in config.toml, created with comments and defaults on first run.

# macOS: ~/Library/Application Support/musicli/config.toml
# Linux: ~/.config/musicli/config.toml

poll_interval_ms = 5000              # check another device's playback (min 4000)
seek_step_ms = 5000                  # how far > and < seek
volume_step = 5                      # how much + and - change the volume
keep_audio = true                    # keep audio on disk so replays start at once
keep_audio_mb = 1024
keep_album_art = true
keep_album_art_mb = 200
start_page = "home"                  # or "library"
classic_view = false                 # the earlier one-page layout (V toggles)
list_density = "comfortable"         # or "compact" (v toggles)
visualizer_only_fullscreen = true
fps = 120
mouse = true
autoplay = true
reduced_motion = false
enable_notifications = true
screensaver_timeout_minutes = 2      # 0 turns it off

Settings files from earlier versions keep working: the old names of renamed keys are still read.

##Updating

To update the terminal app, run the install command again. It always fetches the latest release from this site:

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

musicli also has a built-in updater: when it finds a newer release the top bar shows Update ready U, and musicli --update installs it after checking its published checksum. To update the desktop app, download the new zip from releases and replace musicli.app in Applications.