First Run

The first run should either open the app or tell you exactly what is missing. No blank screens, no silent auth failure.

Let onboarding drive

spotuify onboard

What you get: config creation, a browser login, and the first sync path in one flow.

The default auth path uses your own Spotify Developer app through Spotify OAuth PKCE. Add the app’s client_id to config when onboarding asks for it. Use redirect URI http://127.0.0.1:8888/callback in the Spotify dashboard. Premium is required for playback.

BYO Spotify app GA means general availability for users who bring their own Spotify Developer app. It is not broad consumer no-developer setup.

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.

Inspect the config path

spotuify config path
spotuify config get redirect_uri

By default the config lives under the platform config directory as spotuify/spotuify.toml. You can point one invocation at another file:

SPOTUIFY_CONFIG=/tmp/spotuify.toml spotuify config path

Run doctor before debugging the TUI

spotuify doctor --format json

What you get: a structured health report. Use this first for auth, daemon, device, Spotify API, cache, and log-path problems.

Verify device control

spotuify devices --format json
spotuify transfer spotuify-hume
spotuify status

Verify local cache

spotuify sync library --format json
spotuify cache status --format json
spotuify search "liked" --source local --format jsonl

Open the TUI

spotuify

The first screen is Home: saved music, podcasts, recent plays, and a queue panel when a Spotify session is active. If nothing is playing or the current item has ended, Space starts the selected item on Home, Search, Library, or Playlists. Quit the TUI with q; the daemon and playback continue.