Install

Requirements

RadioCLI needs:

Homebrew on macOS: installs RadioCLI, Node.js, mpv, and FFmpeg
npm, pnpm, or Bun on macOS, Linux, and Windows: Node.js 22 or newer
mpv for playback, pause, mute, volume, media keys, metadata, and readiness checks
FFmpeg on macOS for experimental AirPlay and optional ffplay fallback
ffplay from FFmpeg as an optional playback-only fallback

Recommended: macOS With Homebrew

Homebrew is the lowest-friction macOS path. The tap formula installs RadioCLI, Node.js, mpv, and FFmpeg through Homebrew:

brew install ciphore/tap/radiocli
radiocli

Run radiocli doctor any time you want to verify local playback readiness.

The npm package is @ciphore/radiocli, and the installed executable is radiocli. npm installs RadioCLI and its JavaScript dependencies only; it does not install system playback tools like mpv or FFmpeg.

npm install -g @ciphore/radiocli
radiocli doctor
radiocli

pnpm and Bun can install the same package for users who already use those package managers:

pnpm add -g @ciphore/radiocli
# or
bun add -g @ciphore/radiocli

The radiocli executable still runs on Node.js 22 or newer, even when installed with pnpm or Bun.

On macOS with npm, install mpv first. Install FFmpeg too if you want AirPlay:

brew install mpv
brew install ffmpeg

RadioCLI discovers AirPlay/RAOP receivers with Bonjour and decodes streams with FFmpeg. The sender bridge is bundled with RadioCLI, so users should not install extra AirPlay packages manually. Passcode-protected receivers prompt in the TUI; enter the code with :airplay-code 1234 or the AirPlay Code screen. RadioCLI requires an explicit AirPlay receiver selection from Settings or :airplay before it tunes through AirPlay. Changing Audio output while a station is playing retunes the station immediately, so users can move between AirPlay and this device without restarting RadioCLI. AirPlay is not used as the automatic startup fallback; restart launches back into local playback while remembering the last receiver for the next manual AirPlay switch.

Linux

On Debian/Ubuntu:

sudo apt install mpv
npm install -g @ciphore/radiocli
radiocli

Other common Linux packages:

sudo dnf install mpv       # Fedora/RHEL-like
sudo pacman -S mpv         # Arch/Manjaro
sudo apk add mpv           # Alpine
sudo zypper install mpv    # openSUSE/SUSE

Then install RadioCLI with npm:

npm install -g @ciphore/radiocli
radiocli doctor
radiocli

Windows

Use Windows Terminal or PowerShell with Node.js 22 or newer and native mpv:

winget install --id OpenJS.NodeJS.LTS -e
winget install --id shinchiro.mpv -e
npm install -g @ciphore/radiocli
radiocli doctor
radiocli

Scoop users can install mpv through the extras bucket instead:

scoop bucket add extras
scoop install mpv

WSL remains supported through the Linux install path, but native Windows is the recommended Windows Terminal path.

Optional ffplay Fallback

Install FFmpeg separately only if you want ffplay fallback support:

macOS/Linux:

brew install ffmpeg        # macOS
sudo apt install ffmpeg

Windows:

winget install --id Gyan.FFmpeg -e

ffplay can tune streams when mpv is unavailable, but it does not provide reliable pause, mute, volume, play/pause media-key, metadata, or readiness control. In ffplay mode RadioCLI labels the backend as ffplay fallback, shows limited-control footer text, and radiocli doctor reports controls=limited.

CI covers command-mode typecheck, tests, builds, package checks, and fresh install smoke checks on Ubuntu, macOS, and Windows.

Local Checkout

git clone https://github.com/Ciphore/RadioCLI.git
cd RadioCLI
npm ci
npm run build
npm link
radiocli

If you do not want to link the package globally:

npm run dev

Built Binary

After a local build, the same command-mode actions can be run directly:

node dist/cli.js check
node dist/cli.js search "lagos talk"

Data Paths And Migration

The npm package is @ciphore/radiocli, and the installed executable is radiocli. Current installs use RadioCLI storage and cache paths such as radiocli.json and radiocli-cache.json.

Existing Radio Atlas data is still discovered when a new RadioCLI store does not exist, and legacy RADIO_ATLAS_HOME / RADIO_ATLAS_DISABLE_ANIMATION environment variables remain supported as migration fallbacks. New automation should use RADIOCLI_HOME and RADIOCLI_DISABLE_ANIMATION.

Next: Use the CLI or learn the TUI controls.