032a6ebed8
Replace the static one-page index.html with a Node-based docs site generator. Sidebar nav, per-page TOC, dark mode toggle (system-pref default, persisted), and a Spotify-green theme with animated equalizer brand mark and ambient hero gradient. Adds 11 hand-written doc pages (index, install, quickstart, auth, playback, library, queue, devices, engines, output, agents, troubleshooting, commands) alongside existing spec.md and RELEASING.md. Pages workflow deploys dist/docs-site to GitHub Pages on push to main; repo Pages source is now "GitHub Actions" instead of legacy /docs.
5.8 KiB
5.8 KiB
| title | description |
|---|---|
| Command Reference | Every spogo subcommand and flag, organized by topic. The machine-readable spec is at spec.md. |
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 |
--engine <name> |
connect |
auto / connect / web / applescript. |
--json |
off | JSON output. |
--plain |
off | Plain (TSV) output. |
--no-color |
auto | Disable color in human output. |
-q, --quiet |
off | Suppress non-essential stderr. |
-v, --verbose |
off | Verbose stderr. |
-d, --debug |
off | Debug stderr (HTTP traces). |
--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. |
auth
Cookie 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. |
search
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. |
info
Fetch a single item by ID, URI, or URL.
| Command | Returns |
|---|---|
| `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
Drive what's playing. See Playback.
| Command | Purpose |
|---|---|
| `spogo play [<id | url>] [--type ] [--shuffle]` |
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>` |
spogo volume <0-100> |
Set device volume. |
| `spogo shuffle <on | off>` |
| `spogo repeat <off | track |
spogo status |
Print currently playing item + device. |
queue
Up-next list. See Queue.
| Command | Purpose |
|---|---|
| `spogo queue add <id | url>` |
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...>` |
| `spogo library tracks remove <id | url...>` |
spogo library albums list [--limit N] |
List saved albums. |
| `spogo library albums add <id | url...>` |
| `spogo library albums remove <id | url...>` |
spogo library artists list [--limit N] [--after <artist-id>] |
List followed artists. |
| `spogo library artists follow <id | url...>` |
| `spogo library artists unfollow <id | url...>` |
spogo library playlists list [--limit N] |
List owned/followed playlists. |
playlist
Mutate playlists. See Library.
| Command | Purpose |
|---|---|
spogo playlist create <name> [--public] [--collab] |
Create a new playlist. |
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, URL, or owned-playlist name.
device
Connect devices. See Devices.
| Command | Purpose |
|---|---|
spogo device list |
List Connect-visible devices. |
| `spogo device set <name | id>` |
Exit codes
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Generic failure |
2 |
Invalid usage / validation |
3 |
Auth / cookies missing or invalid |
4 |
Network / timeouts |
See Output for the full output contract.