Spotify Soloist Command Line

Daemon CLI


_10soloist -n NAME -k KEY [options]

For the local JSON API, see WebSocket API. For local status, observe, and control commands, see soloist ctl.

Required options

Option	Description
`-n, --device-name NAME`	Spotify Connect device name.
`-k, --api-key KEY`	Spotify Soloist API key from Spotify for Developers. Treat this value as a secret.

Storage options

Option	Description
`-D, --data-dir PATH`	Persistent data directory for device state and stored session.
`-C, --cache-dir PATH`	Cache directory for volatile playback cache.
`-z, --cache-size MB`	Maximum cache size in MB. Use `0` for no limit. Values must be `0` or at least `100`. Default is no limit.

On Linux, the data directory defaults to $STATE_DIRECTORY, then $XDG_DATA_HOME/soloist, then ~/.local/share/soloist. The cache directory defaults to $CACHE_DIRECTORY, then $XDG_CACHE_HOME/soloist, then ~/.cache/soloist.

While Spotify Soloist is running, the data directory may contain soloist.pid, ws.addr, and ws.port. The data directory also stores local crash reports. soloist ctl uses the runtime files for same-machine status and WebSocket endpoint discovery.

Playback and audio options

Spotify Soloist plays audio through PipeWire or PulseAudio on Linux. By default, it uses the system's default audio output. --pipewire-device applies only when Spotify Soloist is using PipeWire.

Option	Description
`-d, --pipewire-device DEVICE`	Route audio to a specific PipeWire node name or ID.
`-i, --initial-volume N`	Initial volume from `0` to `100`. If omitted, Spotify Soloist uses the audio system's current/default volume.
`-s, --single-track URI`	Play one Spotify URI and exit when done.
`-p, --pair`	Authenticate through Spotify Connect, store credentials, and exit. Use before single-track mode or to replace the stored session.

--pair and --single-track are mutually exclusive. --single-track is for one Spotify URI, not broader playback contexts.

WebSocket and diagnostics options

Option	Description
`-w, --ws ADDR:PORT`	Enable the local WebSocket API on the given address and port. Use port `0` to let the operating system choose a free port.
`-v, --verbose`	Show verbose logs.
`-V, --version`	Print version and exit.
`-h, --help`	Print help and exit.

If the WebSocket server cannot listen on the requested address and port, Spotify Soloist starts without the WebSocket API and logs a warning.

Exit codes

These exit codes are for the Spotify Soloist daemon.

Code	Meaning
`0`	Success. This includes `--help`, `--version`, successful pair mode, successful single-track mode, and normal daemon shutdown.
`1`	General failure. Check stderr and logs for the specific cause, such as invalid arguments, missing required options, invalid single-track URI, unwritable data or cache directory, another Spotify Soloist process already using the data directory, invalid build timestamp, startup failure, or playback failure in single-track mode.
`10`	Spotify Soloist build expired. Install a newer build before starting Spotify Soloist again.

soloist ctl has its own exit codes; see soloist ctl.