Command Line (nokkvi CLI)

nokkvi <verb> sends a single command to the running Nokkvi instance over a Unix socket and exits. Use it from shell scripts, window manager keybinds, or any external tool — there’s no GUI startup cost because the CLI path returns before iced initializes.

The CLI is an alternative to MPRIS. MPRIS covers the standard transport surface and works with any MPRIS controller; the CLI adds verbs that MPRIS doesn’t expose (switch-view, love, rate, clear-queue, consume).

Verbs

Transport

Verb	Arg	Action
play	—	Start playback
pause	—	Pause playback
play-pause	—	Toggle play / pause
stop	—	Stop and reset the playhead
next	—	Skip to the next track
previous	—	Return to the previous track
seek	<seconds>	Seek to absolute position (float, in seconds)
volume	<value>	Set volume — see Volume syntax

Queue and modes

Verb	Arg	Action
shuffle	—	Toggle random mode
repeat	—	Cycle repeat: off → one → queue
consume	—	Toggle consume mode
clear-queue	—	Empty the queue and stop playback
add-to-queue	—	Add the focused list item to the queue — the in-app Shift+A
remove-from-queue	—	Remove the centered queue song — Ctrl+D; errors not_in_queue_view outside the queue view

View

Verb	Arg	Action
switch-view	<view>	Switch the top pane — see View names

Navigation

Verb	Arg	Action
nav-up	—	Move the focused list selection up — Backspace
nav-down	—	Move the focused list selection down — Tab
enter	—	Activate the centered item — play / expand / edit

nav-up, nav-down, and enter are fire-and-forget; the move is async, so query selection afterward to read where focus landed.

Query

These are pure reads — they print JSON and change nothing.

Verb	Arg	Action
status	—	Print playback state, track, album, position, duration, volume, and the three modes as JSON
selection	—	Print the focused view’s centered item as JSON: view, kind, name, artist, rating, starred; kind is null when nothing is selectable

Playing track

These act on whatever’s currently playing and exit 1 with a no_playing_track error if nothing is loaded.

Verb	Arg	Action
love	—	Toggle Navidrome star on the playing track
rate	<delta-or-abs>	Adjust the playing track rating — see Rating syntax

Misc

Verb	Arg	Action
ping	—	Probe the running instance. Prints pong and exits 0.
-h, --help	—	Print usage and the full verb catalog, then exit 0.
-V, --version	—	Print nokkvi <version>, then exit 0.

Argument syntax

Volume syntax

The <value> arg accepts two shapes:

• Delta — +N or -N, added to the current volume and clamped silently to 0.0..=1.0. Repeated volume +0.05 at the ceiling is a no-op.
• Absolute — N in 0.0..=1.0. Out-of-range values error rather than clamp.

nokkvi volume +0.05    # bump 5%
nokkvi volume -0.1     # drop 10%
nokkvi volume 0.5      # set to 50%

Rating syntax

The <delta-or-abs> arg accepts two shapes:

• Delta — +N or -N, added to the current rating and clamped to 0..=5.
• Absolute — 0 through 5. Out-of-range values error.

nokkvi rate +1    # bump by one star
nokkvi rate -1    # drop by one star
nokkvi rate 5     # set to five stars
nokkvi rate 0     # clear the rating

To confirm each change with a desktop notification — useful when you’ve bound these to a window-manager keybind — enable rating_change_notification_enabled.

View names

switch-view accepts one of: albums, queue, songs, artists, genres, playlists, radios, settings. Anything else errors with the full list in the message.

nokkvi switch-view albums
nokkvi switch-view queue

How it connects

Each running Nokkvi daemon binds a per-PID socket so multiple instances can coexist:

Environment	Socket path
$XDG_RUNTIME_DIR set	$XDG_RUNTIME_DIR/nokkvi-{pid}.sock
Unset (fallback)	/tmp/nokkvi-{uid}-{pid}.sock

The {uid} in the fallback path comes from the $UID environment variable, not the kernel uid. When $UID is unset it falls back to the literal default (e.g. /tmp/nokkvi-default-{pid}.sock).

The CLI auto-discovers the live socket — you don’t pass a path. If no instance is running, the command exits 1 with a message listing the directory it searched.

Exit codes

Code	Meaning
0	Server accepted the verb. Any payload is printed to stdout (e.g. ping prints pong).
1	No live instance found, or the server returned an error (e.g. invalid_args, no_playing_track, unavailable, not_in_queue_view). Error message goes to stderr.

Hyprland keybinds

Hyprland’s Lua config is the current binding API — hl.bind(keys, hl.dsp.exec_cmd(cmd), opts?) matches the shape from the upstream example/hyprland.lua. The Lua block below is the author’s actual ~/.config/hypr/keybinds.lua for nokkvi; the legacy .conf tab is for stable distros still on the older Hyprland.

Lua (current)

-- ~/.config/hypr/keybinds.lua
local mod_alt = "SUPER + ALT"

-- Transport
hl.bind(mod_alt .. " + space", hl.dsp.exec_cmd("nokkvi play-pause"))
hl.bind(mod_alt .. " + right", hl.dsp.exec_cmd("nokkvi next"))
hl.bind(mod_alt .. " + left",  hl.dsp.exec_cmd("nokkvi previous"))

-- Volume — { repeating = true } repeats while held
hl.bind(mod_alt .. " + up",    hl.dsp.exec_cmd("nokkvi volume +0.01"), { repeating = true })
hl.bind(mod_alt .. " + down",  hl.dsp.exec_cmd("nokkvi volume -0.01"), { repeating = true })

-- Rating + love on the currently playing track
hl.bind(mod_alt .. " + L",     hl.dsp.exec_cmd("nokkvi love"))
hl.bind(mod_alt .. " + equal", hl.dsp.exec_cmd("nokkvi rate +1"))
hl.bind(mod_alt .. " + minus", hl.dsp.exec_cmd("nokkvi rate -1"))

Legacy .conf

~/.config/hypr/hyprland.conf

# Transport
bind  = $mainMod ALT, space, exec, nokkvi play-pause
bind  = $mainMod ALT, right, exec, nokkvi next
bind  = $mainMod ALT, left,  exec, nokkvi previous

# Volume (binde repeats while held)
binde = $mainMod ALT, up,   exec, nokkvi volume +0.01
binde = $mainMod ALT, down, exec, nokkvi volume -0.01

# Rating + love on the currently playing track
bind  = $mainMod ALT, L,     exec, nokkvi love
bind  = $mainMod ALT, equal, exec, nokkvi rate +1
bind  = $mainMod ALT, minus, exec, nokkvi rate -1

Add { locked = true } (Lua) or use bindl/bindle (.conf) on any bind you want to keep working while the session is locked — the upstream example sets it on XF86Audio* keys.

Other window managers

The CLI is a plain executable — use whatever your compositor’s exec-keybind syntax is (sway’s bindsym, i3’s bindsym, dwm’s config.h, etc.) and call nokkvi <verb> from it.