Spotify Soloist Command Line

Daemon CLI

The examples use soloist for an executable on your PATH. From the extracted directory, use ./soloist on Linux and macOS or .\soloist.exe in Windows PowerShell. See command examples on each platform for shell syntax.


_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.

The default directories are:

Platform	Default data directory	Default cache directory
Linux	`~/.local/share/soloist`	`~/.cache/soloist`
macOS	`~/Library/Application Support/soloist`	`~/Library/Caches/soloist`
Windows	`%LOCALAPPDATA%\soloist\data`	`%LOCALAPPDATA%\soloist\cache`

On Linux, environment variables can override these defaults:

Data: use $STATE_DIRECTORY first, then $XDG_DATA_HOME/soloist, then the default above.
Cache: use $CACHE_DIRECTORY first, then $XDG_CACHE_HOME/soloist, then the default above.

%LOCALAPPDATA% refers to the Windows local application data directory. In PowerShell, use $env:LOCALAPPDATA to refer to it. Quote paths that contain spaces when you pass --data-dir or --cache-dir.

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

Playback and audio options

Spotify Soloist uses PipeWire or PulseAudio on Linux, Core Audio on macOS, and WASAPI on Windows. 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.