Install

Choose Your Install

Use npm on macOS, Linux, or Windows when Node.js 22 or newer is already installed:

npm install -g @ciphore/radiocli
radiocli setup
radiocli

On macOS, Homebrew is the all-in-one option because the formula also installs Node.js, mpv, and FFmpeg:

brew install ciphore/tap/radiocli
radiocli

Both paths install the same radiocli command. The npm package is the universal option; its guided radiocli setup step installs selected system playback tools through Homebrew, WinGet, Scoop, Chocolatey, or the detected Linux package manager.

Upgrade An Existing Installation

RadioCLI preserves preferences, favorites, history, alarms, and agent settings outside the installed package. Check or install the latest release with:

radiocli update
radiocli update --install

The detected Homebrew, npm, pnpm, or Bun package manager performs the upgrade. When local agent control is enabled, the install form also repairs detected MCP registrations. RadioCLI registers MCP clients through an upgrade-stable launcher: the package-manager shim on Unix, or the absolute Node and installed CLI paths on Windows so stdio never depends on .cmd shell behavior. Restart RadioCLI and any open agent clients after upgrading. If an installation was moved or an older registration is already stale, run radiocli mcp status followed by radiocli mcp repair.

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
• VLC (cvlc/vlc) as an additional playback-only fallback when mpv and ffplay are unavailable. RadioCLI also probes common install locations (Homebrew, Scoop, WinGet, Chocolatey, and the VLC app bundle) when a binary is not on PATH, so GUI-launched terminals still find it.

Quickest: Try It With npx

If you already have Node.js 22+, run RadioCLI without installing anything:

npx @ciphore/radiocli

This is the fastest way to try the TUI. You still need mpv, ffplay, or VLC for audio — run npx @ciphore/radiocli doctor to check.

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.

Universal npm Install

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 setup
radiocli

The setup receiver detects tools that are already installed, offers mpv, FFmpeg/ffplay, and VLC, shows every native command before it runs, and finishes with playback verification. mpv is selected by default everywhere. FFmpeg is also selected by default on macOS because it enables experimental AirPlay.

RADIOCLI  SETUP RECEIVER
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
System  macOS Apple Silicon · Node v22.18.0
Manager brew

Choose components (installed items will be skipped):
  mpv      Full playback controls (Y/n)
  FFmpeg   AirPlay + ffplay fallback (Y/n)
  VLC      Additional playback fallback (y/N)
  Agent control via MCP (detected coding agents) (Y/n)
  Open the RadioCLI TUI for agent playback (macOS will ask the agent app to control Terminal on first use) (Y/n)

For automation or to inspect the plan first:

radiocli setup --yes                   # recommended defaults
radiocli setup --all --yes             # mpv, FFmpeg, and VLC
radiocli setup --only mpv,ffmpeg       # explicit selection
radiocli setup --dry-run               # print commands only
radiocli setup --mcp                   # enable and configure detected MCP clients
radiocli setup --mcp --agent-ui        # open a separate terminal TUI (default)
radiocli setup --mcp --headless-agent  # opt out of external terminal windows
radiocli setup --no-mcp                # disable/remove MCP entries

Agent playback opens the RadioCLI TUI in a terminal window by default on every platform. On macOS, the first request from each agent host (for example, ChatGPT) also produces Apple's Automation consent dialog. RadioCLI cannot grant that permission on the host's behalf; approve it when prompted. If a user does not want external terminal windows or OS app-control prompts, choose headless mode during setup or under Settings → Agent control & MCP.

RadioCLI uses an animated activity bar and elapsed time while each package manager runs. Package managers do not report a portable, reliable percentage, so the bar intentionally shows activity rather than inventing completion data. In redirected output or CI, setup emits plain start/result log lines instead.

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 setup
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 setup
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 setup
radiocli

The WinGet package currently installs mpv.exe under Program Files\MPV Player without adding it to PATH. RadioCLI checks that directory and Windows' registered application locations directly, so reopening the terminal or editing PATH is not required. radiocli doctor prints the resolved path, discovery method, version, and whether the executable launches successfully.

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.

Alarm Scheduling Requirements

Radio alarms use the native per-user scheduler, with no additional setup inside RadioCLI on supported hosts:

• macOS uses launchd LaunchAgents.
• Native Windows uses Task Scheduler interactive-token tasks.
• Linux requires a working systemd user manager and systemctl --user.

Linux systems without systemd user scheduling are reported as unsupported; WSL must provide a working user manager and an interactive audio path to use alarms. All platforms require a logged-in audio session and local speakers when the job runs. The terminal itself may close after an alarm is saved and registered. At firing time RadioCLI opens the supported terminal captured during scheduling and shows its ringing controls, or reuses an existing RadioCLI TUI. Unsupported integrated terminals fall back to a platform terminal when possible.

Run radiocli alarm doctor to check scheduler and sleep-inhibitor readiness, and radiocli alarm sync after restoring a backup or changing the host timezone. Wake-from-sleep is best-effort, not a promise that the computer will wake from every sleep, lid, hibernate, or power state. See Reliability for the platform matrix and Alarm Guard tradeoffs.

Local Checkout

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

Native alarm jobs retain the Node executable and built dist/cli.js paths that existed when they were registered. After moving the checkout, changing the Node installation, or rebuilding at a new path, run radiocli alarm sync.

Because npm and source installs run through Node, macOS may label their Background Activity entry as node. RadioCLI does not disguise that process; native RadioCLI naming requires a separately distributed, signed macOS app and bundled helper.

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.