Control Spotify with Hermes

Hermes can search Spotify, inspect playback, manage playlists and saved music, and—on Premium accounts—control playback and queues. The integration uses Spotify's official Web API with PKCE OAuth, so each operator creates a small Spotify developer app but does not need a client secret.

Enable and authenticate

Run hermes tools, enable the Spotify toolset, and complete the inline wizard; or enable it first and run hermes auth spotify separately. Register the exact callback URL shown by Hermes—normally http://127.0.0.1:43827/spotify/callback—and provide the Client ID. Tokens are stored in Hermes authentication state and refresh automatically.

Free accounts can search, inspect history and devices, and manage playlists, albums, and the saved library. Premium is required for play, pause, skip, seek, repeat, shuffle, volume, queue additions, and device transfer. Playback mutations also require an active Spotify Connect device.

Setup checklist

Create a personal Spotify developer app with Web API enabled.
Register the exact loopback redirect URI.
Enable the Spotify toolset before expecting tools to appear.
Complete hermes auth spotify and check status.
Open Spotify on at least one Connect-capable device.
Match automation plans to Free or Premium capability.

Remote-host note

Over SSH, forward the callback port from the local browser to the remote Hermes host. The browser can complete consent only if the loopback callback reaches the process that started authentication.

Pitfalls

“No active device” is not an authentication error; open Spotify and start playback briefly. A 204 currently-playing response usually means nothing is playing. Redirect URI mismatches cause INVALID_CLIENT. Tight automation loops can hit Spotify rate limits. Scheduled playback also fails if the target device is asleep or unavailable when cron fires.

Verification steps

Run hermes auth status spotify and confirm valid tokens.
Ask Hermes to list devices and search for one known artist.
On Premium, transfer playback to a named active device and pause it.
Create or edit a test playlist, then verify it in Spotify.
Revoke access only after confirming sign-out requirements.

Read the official Spotify guide for the current tool matrix, OAuth flow, and troubleshooting advice.