👋 Introduction

Qobuz from the command line — search, library, playlists, deep-link open, and media-key playback control

qobuz-cli brings Qobuz to your terminal: search the catalogue, manage favourites and playlists, open anything in the desktop app, and drive playback — without leaving the shell. It's a thin surface over the @kud/qobuz core: the library does the work, the CLI formats the output.

🎛️ How it fits together

Two halves work in tandem:

The API side — search, metadata, and library/playlist management talk to Qobuz through the core library, authenticated by a browser-borrowed token in your macOS Keychain.
The playback side — play, next, previous, and friends drive the Qobuz desktop app via real media keys (macOS, needs Accessibility permission), and open / url deep-link into it. The CLI steers the app you already have; it doesn't stream audio itself.

📦 Install

npm install -g @kud/qobuz-cli

📖 What's here

🔐 Authentication — log in with a browser-borrowed token, stored in the Keychain.
🔍 Search & metadata — find albums, tracks, and artists, and inspect their details.
📚 Library — manage favourites and create or edit playlists.
▶️ Playback & opening — media-key control, deep-link open, and clipboard url.

⚡ First run

Authenticate once — qobuz login opens the Qobuz web player and asks you to paste a session token from your logged-in browser (Qobuz gates password login behind captchas, so the CLI borrows the browser's token instead). The token is validated and stored in the macOS Keychain:

$ qobuz login
Connect your Qobuz account.
In the page that opens: log in, then DevTools → Network, click any
request to www.qobuz.com/api.json and copy these from its headers:

  X-App-Id [123456789]:
  X-User-Auth-Token: ································

  Validating… ✓ connected. Session saved to the Keychain (service "qobuz").

From then on every command reuses that stored session. Full detail on the Authentication page.

$ qobuz search "radiohead"
$ qobuz fav add albums 0634904032432
$ qobuz open album 0634904032432

🗺️ Command map

Command	What it does
`qobuz login` / `logout`	Connect (store token) / disconnect (clear Keychain).
`qobuz search <query>`	Search albums, artists, and tracks in one call.
`qobuz album\|artist\|track <id>`	Show metadata for one item.
`qobuz similar <artistId>`	Artists similar to the given one.
`qobuz fav list\|add\|remove`	Manage favourites.
`qobuz playlist list\|show\|create\|add\|remove`	Manage playlists.
`qobuz stats`	Collection analytics from the local desktop library.
`qobuz url [type] [id]` (alias `copy-url`)	Copy a deep link — the playing track, or a given item.
`qobuz open <type> <id>`	Open an item in the Qobuz app.
`qobuz play\|next\|previous\|forward\|rewind`	Control the active player via media keys (macOS).

Every command groups onto a page: auth on Authentication, browsing/metadata on Search & metadata, favourites and playlists on Library, and the desktop-control commands on Playback & opening.

🛠️ Built-in help

Citty (the arg parser) gives every command and subcommand a --help:

$ qobuz --help
$ qobuz playlist --help
$ qobuz fav add --help

🧑‍💻 Develop from source

Clone the repo, then iterate against the core without rebuilding:

npm install
npm run dev -- search "radiohead"   # run from source via tsx
npm run build                        # compile native helper + bundle with tsup
npm run typecheck

There's no start script — it isn't meaningful for a CLI. npm run dev -- <args> runs the TypeScript entry directly through tsx; everything after -- is passed to qobuz.