Spotify

Hermes can control Spotify directly — playback, queue, search, playlists, saved tracks/albums, and listening history — using Spotify's official Web API with PKCE OAuth. Tokens are stored in ~/.hermes/auth.json and refreshed automatically on 401; you only log in once per machine.

Unlike Hermes' built-in OAuth integrations (Google, GitHub Copilot, Codex), Spotify requires every user to register their own lightweight developer app. Spotify does not let third parties ship a public OAuth app that anyone can use. It takes about two minutes and hermes auth spotify walks you through it.

Prerequisites

• A Spotify account. Free works for search, playlist, library, and activity tools. Premium is required for playback control (play, pause, skip, seek, volume, queue add, transfer).
• Hermes Agent installed and running.
• For playback tools: an active Spotify Connect device — the Spotify app must be open on at least one device (phone, desktop, web player, speaker) so the Web API has something to control. If nothing is active you'll get a 403 Forbidden with a "no active device" message; open Spotify on any device and retry.

Setup

One-shot: hermes tools

The fastest path. Run:

hermes tools

Scroll to 🎵 Spotify, press space to toggle it on, then s to save. Hermes drops you straight into the OAuth flow — if you don't have a Spotify app yet, it walks you through creating one inline. Once you finish, the toolset is enabled AND authenticated in one pass.

If you prefer to do the steps separately (or you're re-authing later), use the two-step flow below.

Two-step flow

1. Enable the toolset

hermes tools

Toggle 🎵 Spotify on, save, and when the inline wizard opens, dismiss it (Ctrl+C). The toolset stays on; only the auth step is deferred.

2. Run the login wizard

hermes auth spotify

The 7 Spotify tools only appear in the agent's toolset after step 1 — they're off by default so users who don't want them don't ship extra tool schemas on every API call.

If no HERMES_SPOTIFY_CLIENT_ID is set, Hermes walks you through the app registration inline:

1. Opens https://developer.spotify.com/dashboard in your browser
2. Prints the exact values to paste into Spotify's "Create app" form
3. Prompts you for the Client ID you get back
4. Saves it to ~/.hermes/.env so future runs skip this step
5. Continues straight into the OAuth consent flow

After you approve, tokens are written under providers.spotify in ~/.hermes/auth.json. The active inference provider is NOT changed — Spotify auth is independent of your LLM provider.

Creating the Spotify app (what the wizard asks for)

When the dashboard opens, click Create app and fill in:

| Field | Value | |lang: ru

-|-------| | Название приложения | что-нибудь (например, hermes-agent) | | Описание приложения | что-нибудь (например, personal Hermes integration) | | Веб-сайт | оставить пустым | | URI перенаправления | http://127.0.0.1:43827/spotify/callback | | Which API/SDKs? | check Web API |

Agree to the terms and click Save. On the next page click Settings → copy the Client ID and paste it into the Hermes prompt. That's the only value Hermes needs — PKCE doesn't use a client secret.

Running over SSH / in a headless environment

If SSH_CLIENT or SSH_TTY is set, Hermes skips the automatic browser open during both the wizard and the OAuth step. Copy the dashboard URL and the authorization URL Hermes prints, open them in a browser on your local machine, and proceed normally — the local HTTP listener still runs on the remote host on port 43827. If you need to reach it through an SSH tunnel, forward that port: ssh -L 43827:127.0.0.1:43827 удаленный.

Verify

hermes auth status spotify

Shows whether tokens are present and when the access token expires. Refresh is automatic: when any Spotify API call returns 401, the client exchanges the refresh token and retries once. Refresh tokens persist across Hermes restarts, so you only re-auth if you revoke the app in your Spotify account settings or run hermes авторизация и выход из системы Spotify.

Using it

Once logged in, the agent has access to 7 Spotify tools. You talk to the agent naturally — it picks the right tool and action. For the best behavior, the agent loads a companion skill that teaches canonical usage patterns (single-search-then-play, when not to preflight get_state, etc.).

> play some miles davis
> what am I listening to
> add this track to my Late Night Jazz playlist
> skip to the next song
> make a new playlist called "Focus 2026" and add the last three songs I played
> which of my saved albums are by Radiohead
> search for acoustic covers of Blackbird
> transfer playback to my kitchen speaker

Tool reference

All playback-mutating actions accept an optional device_id to target a specific device. If omitted, Spotify uses the currently active device.

spotify_playback

Control and inspect playback, plus fetch recently played history.

spotify_devices

spotify_queue

spotify_search

Search the catalog. query is required. Optional: types (array of track / album@@IC005 0@@artist / playlist / show / episode), limit, offset, market.

spotify_playlists

spotify_albums

spotify_library

Unified access to saved tracks and saved albums. Pick the collection with the kind arg.

Required: kind@@IC00 95@@tracks or albums, plus action.

Feature matrix: Free vs Premium

Read-only tools work on Free accounts. Anything that mutates playback or the queue requires Premium.

Scheduling: Spotify + cron

Because Spotify tools are regular Hermes tools, a cron job running in a Hermes session can trigger playback on any schedule. No new code needed.

Morning wake-up playlist

hermes cron add \
  --name "morning-commute" \
  "0 7 * * 1-5" \
  "Transfer playback to my kitchen speaker and start my 'Morning Commute' playlist. Volume to 40. Shuffle on."

What happens at 7am every weekday: 1. Cron spins up a headless Hermes session. 2. Agent reads the prompt, calls spotify_devices list to find "kitchen speaker" by name, then spotify_devices Transfer → spotify_playback set_volume → spotify_playback set_shuffle → spotify_search + spotify_playback play. 3. Music starts on the target speaker. Total cost: one session, a few tool calls, no human input.

Wind-down at night

hermes cron add \
  --name "wind-down" \
  "30 22 * * *" \
  "Pause Spotify. Then set volume to 20 so it's quiet when I start it again tomorrow."

Gotchas

• An active device must exist when the cron fires. If no Spotify client is running (phone/desktop/Connect speaker), playback actions return 403 нет активного устройства. For morning playlists, the trick is to target a device that's always on (Sonos, Echo, a smart speaker) rather than your phone.
• Premium required for anything that mutates playback — play, pause, skip, volume, transfer. Read-only cron jobs (scheduled "email me my recently played tracks") work fine on Free.
• The cron agent inherits your active toolsets. Spotify must be enabled in hermes инструменты for the cron session to see the Spotify tools.
• Cron jobs run with skip_memory=True so they don't write to your memory store.

Full cron reference: Cron Jobs.

Sign out

hermes auth logout spotify

Removes tokens from ~/.hermes/auth.json. To also clear the app config, delete HERMES_SPOTIFY_CLIENT_ID (and HERMES_SPOTIFY_REDIRECT_URI if you set it) from ~/.hermes/.env, or run the wizard again.

To revoke the app on Spotify's side, visit Apps connected to your account and click REMOVE ACCESS.

Troubleshooting

403 Запрещено — команда проигрывателя не выполнена: активное устройство не найдено — You need Spotify running on at least one device. Open the Spotify app on your phone, desktop, or web player, start any track for a second to register it, and retry. spotify_devices list shows what's currently visible.

403 Запрещено — требуется премиум — You're on a Free account trying to use a playback-mutating action. See the feature matrix above.

204 Нет контента on get_currently_playing — nothing is currently playing on any device. This is Spotify's normal response, not an error; Hermes surfaces it as an explanatory empty result (is_playing: false).

INVALID_CLIENT: неверное перенаправление URI — the redirect URI in your Spotify app settings doesn't match what Hermes is using. The default is http://127.0.0.1:43827/spotify/callback. Либо добавьте его к разрешенным URI перенаправления вашего приложения, либо установите HERMES_SPOTIFY_REDIRECT_URI в ~/.hermes/.env на все, что вы зарегистрировали.

429 Too Many Requests — ограничение скорости Spotify. Гермес возвращает дружественную ошибку; подождите минуту и ​​повторите попытку. Если проблема не исчезнет, ​​возможно, у вас в сценарии зациклен цикл — квота Spotify сбрасывается примерно каждые 30 секунд.

401 Unauthorized продолжает возвращаться — ваш токен обновления был отозван (обычно потому, что вы удалили приложение из своей учетной записи или приложение было удалено). Запустите hermes auth spotify еще раз.

Мастер не открывает браузер — если вы используете SSH или находитесь в контейнере без дисплея, Hermes обнаружит это и пропустит автоматическое открытие. Скопируйте URL-адрес информационной панели, которую он печатает, и откройте его вручную.

Дополнительно: пользовательские области

По умолчанию компания Hermes запрашивает прицелы, необходимые для каждого поставляемого инструмента. Переопределите, если вы хотите ограничить доступ:

hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"

Ссылка на область действия: Области действия Spotify Web API. Если вы запрашиваете меньше областей, чем требуется инструменту, вызовы этого инструмента завершатся ошибкой 403.

Дополнительно: собственный идентификатор клиента/URI перенаправления

hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback

Или установите их навсегда в ~/.hermes/.env:

HERMES_SPOTIFY_CLIENT_ID=<your_id>
HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback

URI перенаправления должен быть включен в список разрешенных в настройках вашего приложения Spotify. Значение по умолчанию работает практически у всех — меняйте его только в том случае, если порт 43827 занят.

Где живут вещи