Reference

spogo CLI spec

GitHub Edit page

spogo CLI spec

One-liner: Spotify power CLI using browser cookies or official OAuth; search + playback control. Parser: Kong. Cookies: steipete/sweetcookie (local sweetcookie). OAuth: Spotify Authorization Code with PKCE; no client secret. Output: human by default; --plain or --json. Color: on by default; respects NO_COLOR, TERM=dumb, --no-color. Platforms: macOS, Linux, Windows.

#Usage

spogo [global flags] <command> [args]

#Global flags

  • -h, --help
  • --version
  • -q, --quiet
  • -v, --verbose
  • -d, --debug
  • --json
  • --plain
  • --no-color
  • --config <path> default: os.UserConfigDir()/spogo/config.toml
  • --profile <name> default: default
  • --timeout <dur> default: 10s
  • --market <cc> default: account market or US
  • --language <tag> default: en
  • --device <name|id> default: active device
  • --engine <auto|web|connect|applescript> default: connect (applescript is macOS-only)
  • --auth <cookies|oauth> default: cookies; selects the Web API token provider
  • --spotify-client-id <id> / SPOGO_SPOTIFY_CLIENT_ID
  • --spotify-redirect-uri <uri> / SPOGO_SPOTIFY_REDIRECT_URI
  • --no-input

#Commands

#completion

  • spogo completion <shell>
  • supports bash, zsh, and fish
  • prints shell initialization code to stdout
  • derives commands, flags, and argument values from the CLI model
  • does not load Spotify auth, cookies, or profile configuration

#auth

  • spogo auth status
  • spogo auth import
  • flags: --browser <chrome|brave|edge|firefox|safari> default: chrome
  • --browser-profile <name>
  • --cookie-path <file> (destination JSON cache)
  • --domain <host> default spotify.com
  • when browser reads fail, surface underlying browser-store warnings
  • spogo auth paste
  • reads cookie values from stdin (prompts when interactive)
  • --cookie-path <file> (destination JSON cache)
  • --domain <suffix> default spotify.com
  • --path <path> default /
  • spogo auth clear
  • spogo auth oauth login
  • Authorization Code with PKCE and state validation
  • flags: --client-id, --redirect-uri, --no-open, --wait-timeout
  • callback must be an explicit IPv4/IPv6 loopback URI with a port
  • stores no client secret
  • spogo auth oauth status
  • local-only; never emits token values
  • spogo auth oauth clear
  • removes the OAuth token cache and restores cookie auth selection
  • spogo search track <query> [--limit N] [--offset N]
  • spogo search album <query> [--limit N] [--offset N]
  • spogo search artist <query> [--limit N] [--offset N]
  • spogo search playlist <query> [--limit N] [--offset N]
  • spogo search episode <query> [--limit N] [--offset N]
  • spogo search show <query> [--limit N] [--offset N]

#info

  • spogo track info <id|url>
  • spogo album info <id|url>
  • spogo artist info <id|url>
  • spogo playlist info <id|url>
  • spogo show info <id|url>
  • spogo episode info <id|url>

#playback

  • spogo play [<id|url>] (track/album/playlist/show)
  • optional: --type <track|album|playlist|show|episode> for raw IDs
  • optional: --shuffle enable shuffle before playing (randomizes first track for context URIs)
  • artist URIs play top tracks (starts with the first)
  • spogo pause
  • spogo next
  • spogo prev
  • spogo seek <ms|mm:ss>
  • spogo volume <0-100>
  • spogo shuffle <on|off>
  • spogo repeat <off|track|context>
  • spogo status

#queue

  • spogo queue add <id|url>
  • spogo queue show
  • spogo queue clear (not supported by Spotify API yet)

#library

  • spogo library tracks list [--limit N]
  • spogo library tracks add <id|url...>
  • spogo library tracks remove <id|url...>
  • spogo library albums list [--limit N]
  • spogo library albums add <id|url...>
  • spogo library albums remove <id|url...>
  • spogo library artists list [--limit N] [--after <artist-id>]
  • spogo library artists follow <id|url...>
  • spogo library artists unfollow <id|url...>
  • spogo library playlists list [--limit N]

#user

  • spogo user top-tracks [--period long_term|medium_term|short_term] [--limit N] [--offset N]
  • returns Spotify affinity-ranked tracks, not play counts
  • long_term = years of listening data; medium_term = about 6 months; short_term = about 4 weeks
  • spogo user history [--period long_term|medium_term|short_term] [--limit N] [--after <ms>] [--before <ms>]
  • returns retained recent plays available from Spotify, not a complete listening archive
  • paginates backward with before cursors until it reaches --limit, the selected period, or Spotify's retained history; client cap is 200 items
  • medium_term, short_term, and --after are local lower-bound filters

#playlists

  • spogo playlist create <name> [--public] [--collab]
  • spogo playlist follow <id|uri|url> (save to library; does not change visibility)
  • spogo playlist unfollow <id|uri|url> (remove from library)
  • spogo playlist following <id|uri|url> (check library membership)
  • spogo playlist add <playlist> <track...>
  • spogo playlist remove <playlist> <track...>
  • spogo playlist tracks <playlist> [--limit N]

#devices

  • spogo device list
  • spogo device set <name|id>
  • falls back to Web API transfer when Connect state has no origin device

#Output contract

  • stdout: primary results; human or machine modes.
  • stderr: warnings/errors/logs.
  • --plain: stable tab-separated field order; metadata tabs/newlines are not escaped. See Output for exact columns.
  • --json: stable keys; see Output for actual result shapes.

#Engines

  • auto: connect first; fall back to web for unsupported features or rate limits. Authentication failures skip remote fallback; on macOS, playback status/control can still recover through Spotify.app using AppleScript.
  • connect: internal connect-state endpoints for playback; GraphQL for search/info. Auth/session data and the last active playback route are cached per profile. Internal operations require browser cookies and preserve authentication failures. Public Web API operations use the selected cookies or oauth provider.
  • web: Web API endpoints authenticated by the selected cookies or oauth provider; search/info/playback can fall back to Connect when rate limited, which requires cookies.

#Exit codes

  • 0 success
  • 1 generic failure
  • 2 parser usage/global validation (some command-specific validation returns 1)
  • 3 auth/cookies missing or invalid
  • 4 network/timeouts

#Config / env

  • Env prefix: SPOGO_
  • Precedence: flags > env > config
  • OAuth precedence: command/global flags > env > profile config.
  • Non-secret profile keys: auth, spotify_client_id, spotify_redirect_uri.
  • OAuth token cache: <config-dir>/oauth/<profile>.json, atomic owner-only writes (0600; parent 0700 on POSIX).
  • Client secrets are unsupported: no config key, flag, or environment variable exists.
  • Overrides:
  • SPOGO_TOTP_SECRET_URL (http(s) or file://...)
  • SPOGO_CONNECT_VERSION (connect playback client version)

#Examples

  • spogo auth import --browser chrome
  • spogo auth oauth login --client-id YOUR_SPOTIFY_CLIENT_ID
  • spogo --engine web --auth oauth search track "weezer" --limit 5 --plain
  • spogo search track "weezer" --limit 5 --plain
  • spogo play spotify:track:7hQJA50XrCWABAu5v6QZ4i
  • spogo device list --json
  • spogo playlist create "Road Trip" --public