Command Reference

Hand-written index of every spogo subcommand. The fully normative spec lives in spec.md; this page is the readable browse.

For deeper guides, see Auth, Playback, Library, Queue, Devices, Engines, and Output.

#Global flags

Apply to every command.

Flag	Default	Purpose
`-h`, `--help`	—	Show contextual help.
`--version`	—	Print the spogo version.
`--config <path>`	platform default	Path to a config file.
`--profile <name>`	`default`	Named profile (separate cookies + config).
`--timeout <dur>`	`10s`	HTTP timeout for any single request.
`--market <cc>`	account market or `US`	Two-letter market code.
`--language <tag>`	`en`	Language/locale.
`--device <name\|id>`	active	Target a specific Connect device.
`--engine <name>`	`connect`	`auto` / `connect` / `web` / `applescript`.
`--auth <name>`	`cookies`	Web API auth: `cookies` / `oauth`.
`--spotify-client-id <id>`	profile	Public Spotify application client ID.
`--spotify-redirect-uri <uri>`	profile	Registered loopback OAuth redirect URI.
`--json`	off	JSON output.
`--plain`	off	Plain (TSV) output.
`--no-color`	auto	Disable color in human output.
`-q`, `--quiet`	off	Suppress human result output; JSON/plain and errors remain.
`-v`, `--verbose`	off	Accepted; currently no additional tracing.
`-d`, `--debug`	off	Accepted; currently no additional tracing.
`--no-input`	auto when not a TTY	Refuse interactive prompts.

Env overrides: every global flag has a SPOGO_<NAME> env equivalent. Two extras:

Env	Purpose
`SPOGO_TOTP_SECRET_URL`	Override TOTP secret source (`http(s)` or `file://`).
`SPOGO_CONNECT_VERSION`	Override Connect client version sent to playback endpoints.

#completion

Print shell completion scripts. This command does not read Spotify auth or profile configuration.

Command	Purpose
`spogo completion bash`	Print Bash shell initialization.
`spogo completion zsh`	Print Zsh shell initialization.
`spogo completion fish`	Print fish shell completions.

Load completions for the current session:

# Bash
source <(spogo completion bash)

# Zsh
source <(spogo completion zsh)

# fish
spogo completion fish | source

To enable them permanently, add the appropriate command to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish.

#auth

Cookie and official Spotify OAuth management. See Auth.

Command	Purpose
`spogo auth status`	Show stored cookie state for the current profile.
`spogo auth import [--browser <name>] [--browser-profile <name>] [--cookie-path <file>] [--domain <host>]`	Pull cookies from a browser store.
`spogo auth paste [--cookie-path <file>] [--domain <suffix>] [--path <path>]`	Read cookies from stdin (interactive prompts unless `--no-input`).
`spogo auth clear`	Delete stored cookies for the current profile.
`spogo auth oauth login [--client-id <id>] [--redirect-uri <uri>] [--no-open] [--wait-timeout <dur>]`	Run Authorization Code with PKCE and cache refresh credentials.
`spogo auth oauth status`	Show non-secret local OAuth cache metadata.
`spogo auth oauth clear`	Delete the OAuth token cache and restore cookie auth selection.

#search

Use -- before positional text that begins with a dash, for example spogo search track -- --no-input. Global flags remain valid before or after the command.

Browse the catalog. Each subcommand takes a query plus --limit N and --offset N.

Command	Returns
`spogo search track <query>`	Tracks.
`spogo search album <query>`	Albums.
`spogo search artist <query>`	Artists.
`spogo search playlist <query>`	Playlists.
`spogo search show <query>`	Podcast shows.
`spogo search episode <query>`	Podcast episodes.

Web API search and Connect's Web API fallback read Spotify's plural result containers (tracks, albums, artists, playlists, shows, episodes); CLI search types stay singular.

#info

Fetch a single item by ID, URI, or URL.

Command	Returns
`spogo track info <id\|url>`	One track.
`spogo album info <id\|url>`	Album metadata.
`spogo artist info <id\|url>`	Artist metadata.
`spogo playlist info <id\|url>`	One playlist's metadata.
`spogo show info <id\|url>`	Show metadata.
`spogo episode info <id\|url>`	One episode.

#playback

Drive what's playing. See Playback.

Command	Purpose
`spogo play [<id\|url>] [--type <kind>] [--shuffle]`	Resume, or start a track / album / playlist / show / artist.
`spogo pause`	Pause current playback.
`spogo next`	Skip to the next item.
`spogo prev`	Previous (restart current if past ~3s).
`spogo seek <ms\|mm:ss>`	Seek within the current item.
`spogo volume <0-100>`	Set device volume.
`spogo shuffle <on\|off>`	Toggle shuffle.
`spogo repeat <off\|track\|context>`	Set repeat mode.
`spogo status`	Print currently playing item, album, and device.

#queue

Up-next list. See Queue.

Command	Purpose
`spogo queue add <id\|url>`	Append one item to the queue.
`spogo queue show`	Print currently playing + queued items.
`spogo queue clear`	Not supported by Spotify's API; use `spogo play <something>` to replace the context.

#library

Saved tracks, albums, followed artists, owned/followed playlists. See Library.

Command	Purpose
`spogo library tracks list [--limit N]`	List saved tracks.
`spogo library tracks add <id\|url...>`	Save tracks.
`spogo library tracks remove <id\|url...>`	Unsave tracks.
`spogo library albums list [--limit N]`	List saved albums.
`spogo library albums add <id\|url...>`	Save albums.
`spogo library albums remove <id\|url...>`	Unsave albums.
`spogo library artists list [--limit N] [--after <artist-id>]`	List followed artists.
`spogo library artists follow <id\|url...>`	Follow artists.
`spogo library artists unfollow <id\|url...>`	Unfollow artists.
`spogo library playlists list [--limit N]`	List owned/followed playlists.

#user

Read-only listening data from Spotify's web endpoints.

Command	Purpose
`spogo user top-tracks [--period long_term\|medium_term\|short_term] [--limit N] [--offset N]`	Show Spotify top tracks by affinity ranking.
`spogo user history [--period long_term\|medium_term\|short_term] [--limit N] [--after <ms>] [--before <ms>]`	Show recently played tracks available from Spotify.

Top tracks are Spotify affinity rankings, not play counts.
long_term = years of listening data; medium_term = about 6 months; short_term = about 4 weeks.
Recently played is not a full archive. spogo paginates backward until it reaches --limit (max 200), the selected period, or Spotify's retained history. medium_term, short_term, and --after are local lower-bound filters.

#playlist

Mutate playlists. See Library.

Command	Purpose
`spogo playlist create <name> [--public] [--collab]`	Create a new playlist.
`spogo playlist follow <id\|uri\|url>`	Save a playlist to your library without changing visibility.
`spogo playlist unfollow <id\|uri\|url>`	Remove a playlist from your library.
`spogo playlist following <id\|uri\|url>`	Check membership (`--plain`: true/false; `--json`: following boolean).
`spogo playlist add <playlist> <track...>`	Append tracks.
`spogo playlist remove <playlist> <track...>`	Remove tracks.
`spogo playlist tracks <playlist> [--limit N]`	List a playlist's items.

<playlist> accepts a playlist ID, URI, or URL. Names are not resolved; capture the ID returned by playlist create --json.

#device

Connect devices. See Devices.

Command	Purpose
`spogo device list`	List Connect-visible devices.
`spogo device set <name\|id>`	Transfer playback to a device.

#Exit codes

Code	Meaning
`0`	Success
`1`	Generic failure
`2`	Invalid usage / validation
`3`	Auth credentials missing or invalid
`4`	Network / timeouts

See Output for the full output contract.