▶️ Playback & opening

qobuz-cli doesn't stream audio itself — the official Qobuz app stays the player. Two mechanisms drive it: deep links (open / url) that point the app at an item, and media keys (play / next / previous) that control whatever is currently playing.

🔗 Deep links — open and url

Both take a <type> (album, track, playlist, or artist) and an <id>, and build an open.qobuz.com link.

qobuz url [type] [id] (alias copy-url)

Copies an open.qobuz.com deep link to the clipboard (via pbcopy) and prints what it copied. Two modes:

Current track (no arguments). With nothing after url, it copies the link for whatever Qobuz is playing right now — handy for sharing the song you're listening to:

$ qobuz url
✓ copied https://open.qobuz.com/track/284254940

A specific item. Pass a <type> (album, track, playlist, artist) and <id>:

$ qobuz url album 0634904032432
✓ copied https://open.qobuz.com/album/0634904032432

copy-url is an alias for the same command. Without pbcopy (non-macOS) it falls back to printing the bare link to stdout, so it still composes in a pipe.

Scripting — --plain. Pass --plain to print just the URL to stdout and skip the clipboard entirely. Works in both modes:

$ qobuz url --plain
https://open.qobuz.com/track/284254940

$ NOW=$(qobuz url --plain)        # capture the playing track's URL in a script

How "current track" works. macOS now-playing is a dead end for Qobuz — the app never registers with it (so Control Center sticks on Spotify/Apple Music). Instead, the CLI reads Qobuz's own queue state at ~/Library/Application Support/Qobuz/player-0.json and takes items[currentIndex]. If the app isn't open and playing, you'll get Nothing playing — couldn't read Qobuz's current track.

qobuz open <type> <id>

Opens the item in the Qobuz app (falls back to the web player if the app isn't installed).

$ qobuz open album 0634904032432
opening https://open.qobuz.com/album/0634904032432

An unrecognised <type> exits non-zero with type must be one of: album, track, playlist, artist.

⏯️ Media keys — play, next, previous, forward, rewind

These post synthetic media-key events to the system, exactly like the keys on a keyboard — so they control the active player (Qobuz, when it's playing). They're fire-and-forget: the keys give no confirmation back. (To read what's playing, the CLI goes around macOS via Qobuz's state file — see url above.)

$ qobuz play       # toggle play / pause
$ qobuz next       # skip to the next track
$ qobuz previous   # go to the previous track  (alias: prev)
$ qobuz forward    # fast-forward within the current track  (alias: ff)
$ qobuz rewind     # rewind within the current track  (alias: rew)

Skip vs scrub. next / previous jump between whole tracks; forward / rewind scrub within the current track. They're distinct media keys (NX_KEYTYPE_FAST / NX_KEYTYPE_REWIND), so whether they seek depends on the active player honouring them.

🍏 macOS only + Accessibility permission

Playback control is macOS-only and posts HID events through a tiny Swift helper bundled with the package (compiled on first use via swiftc). For the events to take effect, your terminal app must be granted Accessibility permission:

System Settings → Privacy & Security → Accessibility → enable your terminal (Terminal, iTerm, Ghostty, …).

The spawned helper inherits the terminal's permission. Without it, the command exits cleanly but nothing happens — if a key seems to do nothing, this is almost always why. (Compilation needs the Xcode command-line tools: xcode-select --install.)