Command line

Control a running Sonora from a terminal, a script or a key binding. The commands are part of the sonora binary, so there is nothing else to install.

sonora toggle
sonora current | jq -r .track.title
sonora play -s "What's Up?"
sonora search daft punk --json | jq -r '.[0].link'

A command never starts Sonora. With none running it exits with code 3. Run sonora --help for the full list, or sonora <command> --help for one command.

With Flatpak, run commands through the sandbox: flatpak run io.github.nolight132.sonora next.

Playback

sonora play / pause / toggleResume, pause, or switch between the two
sonora next / prevSkip to the next song, or go back
sonora seek 50 | 1:30 | +10Jump to a percent, to a time, or by a number of seconds
sonora volume [N | +N | -N]Print the volume, set it from 0 to 100, or step it
sonora shuffle [on | off | toggle]Print or switch shuffle
sonora repeat [off | all | one]Print or set repeat

Queue and search

sonora play <file or link>...Play now, then carry on with the queue
sonora play -s <query>Play the best search hit now
sonora add <file or link>...Queue after the songs you queued by hand
sonora play-next <file or link>...Queue right after the current song
sonora add -s <query>Queue the best search hit
sonora search <query> [-n N]Search the current provider

Status and the rest

sonora currentPrint what plays now as JSON
sonora watch [--position]Print a line of JSON on every change
sonora providersList the providers and which one is current
sonora provider [slug]Print the current provider, or switch
sonora session [start | join CODE | leave]Print, start, join or leave a Session
sonora completions <shell>Print a completion script
sonora --versionPrint the version

Details

-s picks a song. Add -t album, -t artist or -t playlist for another kind. Quote a query only when it has characters your shell reads, such as ', ? or &.

Links have to belong to the current provider. Switch first with sonora provider. Relative file paths start from the folder you run the command in. If one item fails, nothing is queued.

While Sonora controls another Spotify device, playback commands go to that device.

A step with seek fits a key binding, for example in Hyprland:

hyprland.conf
bind = SUPER, right, exec, sonora seek +10
bind = SUPER, left, exec, sonora seek -10

Scripts and status bars

Add --json to any command for one line of JSON. current always prints JSON, or null when nothing is loaded. It has the state, the song, the position in seconds, the volume as a percent, shuffle, repeat, the provider, whether the song is liked and what it plays from.

watch prints the same JSON again whenever the song, state, volume, shuffle or repeat changes. --position adds a line every second while a song plays.

sonora watch | jq --unbuffered -r '.track.title // ""'
Exit codeMeaning
0Done
1Sonora refused the command or didn't answer
2The command line is wrong. Nothing was sent.
3Sonora isn't running

Shell completions

Completions exist for bash, zsh, fish, elvish and PowerShell.

sonora completions bash > ~/.local/share/bash-completion/completions/sonora
sonora completions zsh > "${fpath[1]}/_sonora"
sonora completions fish > ~/.config/fish/completions/sonora.fish