Start with
spot auth --status as a first diagnostic step. It confirms whether your credentials are configured and valid, which is the root cause of most issues."spot: command not found"
"spot: command not found"
The Then reload your shell:
~/.cargo/bin directory is not in your PATH. Add the following line to your shell profile (~/.zshrc, ~/.bashrc, or equivalent):Search fails or "credentials not found"
Search fails or "credentials not found"
spot cannot find your Spotify API credentials. Run the interactive setup:You’ll be prompted for your Client ID and Client Secret from developer.spotify.com/dashboard. spot validates and saves them on success.
"Spotify is not running"
"Spotify is not running"
spot uses AppleScript to control the Spotify desktop app. The app must be open before running playback commands.Open the Spotify desktop app, then retry your command.
Controls like
spot pause, spot next, and spot vol all require the Spotify desktop app to be running. Search commands (spot search) do not.Smart play picks the wrong type
Smart play picks the wrong type
Smart play (Then
spot <query>) uses exact, case-insensitive name matching to decide whether to play a track, album, or artist. A partial query won’t match.For example, spot beatles won’t match “The Beatles” because the names differ. Create an alias to map the short name to the full query:spot beatles resolves to “The Beatles” before searching.No liked songs or private playlists
No liked songs or private playlists
spot uses the Client Credentials OAuth flow, which authenticates your app but not your Spotify account. This means user-specific data — liked songs, private playlists, listening history — is not accessible.This is a known limitation of the Client Credentials flow. There is no workaround without implementing user authorization (OAuth Authorization Code flow), which spot does not support.
Token errors or expired credentials
Token errors or expired credentials
If spot reports a token error or your credentials appear invalid after previously working, the cached token file may be stale or corrupt. Delete it and re-authenticate:spot will fetch a fresh token and save it on the next command.
spot doesn't work on Linux or Windows
spot doesn't work on Linux or Windows
spot is macOS-only. Playback and controls rely on AppleScript (
osascript), which is exclusive to macOS. There is no Linux or Windows support.