Install

Install spotuify, log in, then run doctor before you trust playback.

Requirements

Spotify account. Premium is required for local playback through the embedded librespot device (spotuify-hume).
A terminal. Kitty or iTerm2 gives better cover art, but the app has text fallbacks.

spotuify --help

Homebrew

brew tap planetaryescape/spotuify
brew trust --formula planetaryescape/spotuify/spotuify
brew install planetaryescape/spotuify/spotuify
spotuify --help

To update an existing Homebrew install:

brew update
brew upgrade planetaryescape/spotuify/spotuify

brew trust --formula keeps installs working when Homebrew tap-trust checks are enabled for third-party taps.

Release archives include SHA256 checksums and GitHub artifact provenance attestations. macOS binaries are not notarized yet, so Gatekeeper may still ask you to approve the first launch.

Install script

For macOS and Linux x86_64 release archives, the installer downloads both the archive and its published .sha256 file before installing:

curl -fsSLO https://raw.githubusercontent.com/planetaryescape/spotuify/main/install.sh
bash install.sh
spotuify --help

Cargo

cargo install --git https://github.com/planetaryescape/spotuify --locked
spotuify --help

Windows x64

Install the Windows x64 release zip from GitHub Releases. The snippet below resolves the latest release automatically; to pin a specific version, set $Version to its tag (for example "v0.1.73") instead:

$Version = (Invoke-RestMethod "https://api.github.com/repos/planetaryescape/spotuify/releases/latest").tag_name
$Archive = "spotuify-$Version-windows-x86_64.zip"
$Base = "https://github.com/planetaryescape/spotuify/releases/download/$Version"

Invoke-WebRequest "$Base/$Archive" -OutFile $Archive
Invoke-WebRequest "$Base/$Archive.sha256" -OutFile "$Archive.sha256"

$Expected = (Get-Content "$Archive.sha256").Split()[0].ToLowerInvariant()
$Actual = (Get-FileHash $Archive -Algorithm SHA256).Hash.ToLowerInvariant()
if ($Actual -ne $Expected) { throw "checksum mismatch for $Archive" }

Unzip it into a user-owned directory and put that directory on your PATH:

$InstallDir = "$env:LOCALAPPDATA\spotuify\bin"
New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
Expand-Archive $Archive -DestinationPath $InstallDir -Force

$env:Path = "$InstallDir;$env:Path"
[Environment]::SetEnvironmentVariable(
  "Path",
  "$InstallDir;" + [Environment]::GetEnvironmentVariable("Path", "User"),
  "User"
)

spotuify.exe --help

Install the user-level daemon service only when you want spotuify to start at login. On Windows this registers a Task Scheduler logon trigger:

spotuify daemon install-service

Windows x64 is shipped as a release artifact and covered by CI check/test/build plus fake-provider smoke. Real login, playback, and Task Scheduler install are still beta until verified on a real Windows machine. Headless daemon media keys are also limited on Windows because SMTC needs a foreground window handle; keep the TUI open when you need global media-key handling.

Source install on Windows:

cargo install --git https://github.com/planetaryescape/spotuify --locked `
  --no-default-features `
  --features "embedded-playback system-integrations loopback-cpal rodio-backend" `
  spotuify
spotuify.exe --help

macOS app (.dmg)

Prefer a native window over the terminal? The SwiftUI menubar and player app lives in clients/macos/. It is a client of the same local daemon and bundles the spotuify CLI/backend when packaged.

The tag-driven CI release does not build the DMG today; it builds the CLI archives and Homebrew formula. DMGs are built locally with clients/macos/scripts/build-dmg.sh and attached to a release when available.

Choose a release whose Assets list includes a DMG and its checksum on the releases page. The latest CLI release can have no app asset, so a latest/download/Spotuify.dmg URL can return 404.

For example, v0.1.109 publishes these app assets. This is an older app release; its availability does not establish that your backend has the corrections in CLI 0.1.112. Replace the version with the app release you selected:

VERSION="0.1.109"
DMG="Spotuify-${VERSION}.dmg"
BASE="https://github.com/planetaryescape/spotuify/releases/download/v${VERSION}"
curl -fsSLO "$BASE/$DMG"
curl -fsSLO "$BASE/$DMG.sha256"
printf '%s  %s\n' "$(awk 'NR == 1 { print $1 }' "$DMG.sha256")" "$DMG" | shasum -a 256 -c -

The checksum command accepts the published digest-only file as well as a checksum line that includes a filename. Expect Spotuify-0.1.109.dmg: OK for that example. After verification, open the DMG and drag Spotuify.app to Applications.

The app bundles a backend, so compare its release with the installed CLI before expecting the same fixes. The build script signs with a Developer ID when a signing identity is available and notarizes only when SPOTUIFY_NOTARY_PROFILE is set. If the published DMG is unsigned or not notarized, macOS may require first-launch approval.

Staying up to date

The daemon checks GitHub for newer releases (on start, then every few hours) and tells you how to upgrade for the way you installed:

CLI: spotuify update prints the current and latest versions plus the exact upgrade command (--force re-checks now, --format json for scripts).
macOS app: an update banner with an Update Now button, offered after the app verifies that the versioned DMG is reachable. A CLI-only release does not produce an app update offer. Toggle automatic checks under Settings.
TUI: an upgrade banner with the upgrade command.

The check only contacts the public GitHub releases API and sends no identifying data. Disable it entirely with SPOTUIFY_NO_UPDATE_CHECK=1 in the daemon’s environment.

Configure Spotify

spotuify is BYO Spotify app GA: the supported GA setup is for users who can create their own Spotify Developer app. It is not broad consumer no-developer setup yet; that would require a reviewed/shared Spotify app or a product decision to make first-party/keymaster auth the default.

Create a Spotify Developer app at the Spotify Developer Dashboard with redirect URI http://127.0.0.1:8888/callback, then add its client id to your config during onboarding. A client secret is optional for PKCE. Premium is required for playback.

The first-party/keymaster flow still exists for experiments. A fresh setup opts in with SPOTUIFY_USE_FIRST_PARTY=1. After login, a machine with only first-party.json keeps using that credential when the variable is unset, so a daemon restart does not switch to an empty dev-app mode. See Config for the full selection rule.

spotuify login
spotuify doctor

What you get: a browser opens, you approve, and the OAuth token is stored in the local auth file under the app config directory. The doctor report tells you whether auth, daemon, device visibility, and Spotify API access work.

Set your Spotify app

Set the client id in config, or export it before logging in:

export SPOTUIFY_CLIENT_ID=your-app-client-id
spotuify login

A denied request needs its reported cause checked. Use the 403 access checks before changing credentials or app settings.

Check your app’s user allowlist and endpoint access. Spotify accepts Extended Quota Mode applications only from eligible organisations. Individual app owners cannot apply, and this mode is not an automatic fix for a denied write.

Start the daemon

spotuify daemon start
spotuify daemon status --format json

Install the platform user service when you want the daemon to survive shell sessions.

spotuify daemon install-service

First sound

spotuify devices
spotuify play "imagine dragons" --type track

If playback fails with no active device, activate or transfer to the device you want:

spotuify transfer spotuify-hume
spotuify play "imagine dragons"