Engines

spogo can talk to Spotify through one of four engines. Pick whichever matches what you need, or let auto decide.

#Quick pick

Set with --engine <name> per call, or globally with SPOGO_ENGINE. Engine selection is separate from Web API authentication, selected with --auth cookies|oauth or SPOGO_AUTH.

#connect (default)

Talks to Spotify's internal Connect endpoints — the same ones the official desktop and mobile apps use to coordinate playback across devices. spogo's first choice for everything.

Best for

• Playback control (play, pause, next, prev, seek, volume, shuffle, repeat).
• Device discovery and transfer.
• Playlist mutations under heavy use (Connect doesn't hit the Web API rate limits).
• Search and item info via the internal GraphQL surface, including episode lookup.
• Listing followed artists, saved albums/tracks, and playlists; user top tracks and recently played history also use internal endpoints.

Authentication

Connect's internal operations require Spotify browser cookies. When Connect delegates an operation to the public Web API, that operation uses the selected --auth cookies|oauth provider. Missing or rejected cookie credentials are reported before any remote fallback; use explicit --engine web --auth oauth for cookie-free access. Commands implemented directly through the Web API, such as creating playlists, use the selected provider without an internal request.

Tradeoffs

• Saving/removing library tracks or albums, following/unfollowing artists, checking or changing playlist membership, creating playlists, and artist-top-track lookups used by artist playback still require the public Web API.
• Transfers without a Connect origin device, some hardware volume/playback requests, and failed internal catalog/library lookups may also fall back to the public Web API.
• These public-API paths can be rate-limited even with --engine connect; a 429 includes Spotify's retry-after hint whenever one is supplied.

#web

The public Spotify Web API. Slower, lower throughput, and rate-limited according to Spotify's account- and application-specific policies; cookie-derived tokens can encounter aggressive cooldowns, including retry hints measured in hours.

Authentication

Use the existing cookie-derived Web API token with --auth cookies (the default), or the official Authorization Code with PKCE token with --auth oauth. A cookie-free setup is:

spogo auth oauth login --client-id YOUR_SPOTIFY_CLIENT_ID
spogo --engine web --auth oauth search track "weezer"

Best for

• Accounts that can't use Connect (rare — usually corporate or family-restricted).
• Forcing the documented public API for a reproducible test.
• Anything that requires Web API specific endpoints not yet in Connect.

Tradeoffs

• Rate limits can apply even without bulk operations. If you see 429, prefer connect for supported reads and honor the reported retry-after hint; Web-API-only operations cannot bypass that cooldown by switching engines.
• Search/info/playback auto-fall-back to Connect when rate limited, so practical behavior is closer to auto.

#auto

Try connect first, then fall back to web for unsupported features or rate limits. Because Connect is first, auto still requires browser cookies for internal operations even when --auth oauth selects OAuth for the Web API fallback. Authentication failures skip the other remote provider. On macOS, playback status and controls can still recover through the already-local Spotify.app using AppleScript, including when cookies are missing.

spogo --engine auto play spotify:playlist:...

Most users don't need this — connect already falls back to web for the specific paths where it has to. auto is useful when you want explicit fallback behavior across all calls.

The AppleScript last resort is limited to status, play, pause, next, prev, seek, volume, shuffle, and repeat. Search, catalog lookup, library operations, playlists, queue commands, and devices remain remote-only; explicit --engine connect and --engine web never use AppleScript.

#applescript (macOS only)

Playback controls drive the local Spotify desktop app via AppleScript without cookies or remote API requests. Other commands may delegate to a remote engine; selecting AppleScript is not a network-isolation boundary. device list shows only the local Mac.

spogo --engine applescript play
spogo --engine applescript pause
spogo --engine applescript next
spogo --engine applescript status

Best for

• Quick local hotkeys / shortcuts (Raycast, Alfred, sketchybar, etc.) where network round trips are wasted.
• Sandboxed environments where cookie auth is awkward.
• Scripts that just need "pause my Mac's Spotify" without touching cloud state.

Tradeoffs

• macOS only.
• No Connect device list (device list shows just the Mac), no transfers.
• Search, catalog lookups, library, and playlists are not AppleScript operations; explicit applescript may delegate them to its configured remote fallback.

#Setting an engine

Per command:

spogo --engine connect play
spogo --engine web --auth oauth search track "weezer"
spogo --engine applescript pause

Per shell:

export SPOGO_ENGINE=web
export SPOGO_AUTH=oauth

In the shared config file (~/.config/spogo/config.toml on Linux, or the platform config directory):

[profile.default]
engine = "web"
auth = "oauth"

#Diagnosing engine issues

spogo --debug status

--debug is currently accepted without additional tracing. Include the selected engine, command, version, and stderr error when reporting a problem. See Output and Troubleshooting.