soloist ctl command line

soloist ctl connects to a running Spotify Soloist process through the WebSocket API. Most commands require Spotify Soloist to be logged in through Spotify Connect.


_10soloist ctl COMMAND [options]

When soloist ctl runs on the same machine as Spotify Soloist and uses the same data directory, it automatically discovers the WebSocket endpoint. Pass --data-dir to use a different data directory, or pass --ws to connect to an explicit endpoint.

Automatic discovery requires Spotify Soloist to be running with --ws, because ctl reads ws.addr and ws.port from the data directory. The status command can still report whether the daemon is running from soloist.pid when the WebSocket API is not enabled.

Global options

Option	Description
`-D, --data-dir PATH`	Data directory to use for automatic same-machine discovery.
`-w, --ws ADDR:PORT`	Connect directly to a WebSocket endpoint.
`--json`	Print machine-readable JSON for supported observe commands (`now` and `queue`).
`-h, --help`	Show help.

Status

Command	Description
`status`	Show daemon status, WebSocket availability, login state, and active-device state. Does not require login.

Observe

Command	Description
`now`	Show the current playback state.
`now --json`	Print the raw `playback_state` JSON.
`queue [n]`	Show upcoming tracks. Default limit is `10`; `n` must be a positive number.
`queue [n] --json`	Print the raw `queue_changed` JSON.
`trace`	Stream all WebSocket events to stdout until interrupted.

trace writes diagnostic connection messages to stderr. Event data is written to stdout as one line per event:


_10<unix_epoch_ms> <json_event>

Control

Command	Description
`play [uri]`	Resume playback, or start playing a playable Spotify URI such as a track, episode, album, or playlist.
`pause`	Pause playback.
`next`	Skip to the next track.
`prev`	Skip to the previous track or restart the current track.
`seek MS`	Seek to a position in the current track, in milliseconds.
`volume 0-100`	Set volume.
`shuffle on`, `shuffle off`	Enable or disable shuffle. Also accepts `true`, `false`, `1`, or `0`.
`repeat off`, `repeat context`, `repeat track`	Set repeat mode.
`add-to-queue URI`	Add a Spotify track URI to the queue. Other URI types are rejected.
`activate`	Make Spotify Soloist the active Spotify Connect device.
`deactivate`	Give up active-device status.

Control commands exit silently after the WebSocket API accepts and dispatches the command. They print an error and exit with a non-zero code when Spotify Soloist is unreachable, not logged in, or returns an API error.

Exit codes

These exit codes are for soloist ctl.

Code	Meaning
`0`	Success.
`1`	Bad arguments.
`2`	Connection failed.
`3`	Server error, such as not logged in or no response.

The Spotify Soloist daemon exits with code 10 when the build has expired.