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 configurations supported by Homebrew, its formula also installs Node.js, mpv, and FFmpeg:

brew install ciphore/tap/radiocli
radiocli

Both paths install the same radiocli command. The npm package also has experimental community installation paths described below. radiocli setup installs selected system playback tools only after showing a plan and receiving confirmation or --yes. npm lifecycle scripts never install system packages. Consult the platform matrix before selecting a runtime or claiming that a particular OS/CPU combination has been verified.

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 its supported macOS configurations: 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 for experimental macOS/Linux 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.

macOS With Homebrew

The tap formula installs RadioCLI, Node.js, mpv, and FFmpeg through Homebrew. Check Homebrew's current OS/CPU policy; Intel and older macOS installations may need a compatible Node distribution and MacPorts or another native player route. See the platform matrix.

brew install ciphore/tap/radiocli
radiocli

Run radiocli doctor to check executable discovery and launch diagnostics. Add --playback to rehearse local WAV playback through each installed local backend using null or dummy audio. Tuning a station and checking the intended speakers, headphones, or receiver verifies the actual output path.

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 by checking executable availability and awaiting a local WAV decoder rehearsal. Each backend reports passed, failed, or unverified; a successful null/dummy rehearsal does not verify a physical audio device, an AirPlay receiver, or a live network stream. Repeat this check with radiocli doctor --playback --json. Dry runs do not launch playback. mpv is selected by default everywhere. FFmpeg is also selected by default on macOS because it enables experimental AirPlay. Native Linux additionally offers an optional experimental AirPlay setup choice. It is off by default; --yes and --all alone do not enable it or change an existing AirPlay opt-in. macOS keeps its existing FFmpeg default.

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 requests the RadioCLI TUI in a supported installed graphical terminal. Missing desktop/session support is reported explicitly; select --headless-agent for command-only playback. 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, TERM=dumb, screen-reader or reduced-motion mode, setup emits plain start/result log lines instead. ASCII mode and the terminal's color depth also apply to setup.

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

On macOS, RadioCLI discovers AirPlay/RAOP receivers with Bonjour and decodes streams with FFmpeg. The sender is an optional package dependency and must install and load successfully; --omit=optional leaves it out. Sender diagnostics report an absent or unusable bridge. 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

On Omarchy Quattro, setup retains Arch's pacman -S --needed package route. If repository metadata is stale, use Omarchy's supported update workflow before retrying setup; RadioCLI does not run a partial system upgrade or bypass its pacman guard. Its native terminal integration follows your selected desktop terminal while preserving explicit terminal overrides.

Experimental Linux AirPlay is disabled until you opt in for the current library. It needs FFmpeg, avahi-browse, a running Avahi daemon, and an installed, loadable optional sender:

radiocli setup --airplay --dry-run  # inspect packages and service actions
radiocli setup --airplay            # review and accept experimental setup
radiocli doctor
radiocli setup --no-airplay         # disable RadioCLI's Linux AirPlay opt-in

Restart any running RadioCLI session after changing this preference.

Setup has Avahi package recipes for apt and pacman. Arch's avahi package provides the browser and daemon; Debian/Ubuntu use avahi-daemon and avahi-utils. On a systemd host, the reviewed plan can include enabling and starting avahi-daemon.service, a system service for discovery on the local network. Other package or service arrangements receive manual setup guidance. Startup and Doctor never install packages or activate the service. Disabling RadioCLI's opt-in leaves shared packages and system services installed and running.

An absent optional sender requires repairing the RadioCLI installation with optional dependencies included; installing FFmpeg alone does not install the sender. A dry run does not change preferences, install packages, or start services.

After opting in, open Settings → AirPlay or :airplay to discover receivers, then select one explicitly each session. Missing dependencies show Setup required; a temporary discovery or receiver failure stays visible instead of hiding the feature. Unsupported platforms and Linux without the opt-in hide AirPlay controls and suggestions. WSL and Termux remain unsupported even if their tools are installed.

Linux startup never scans for receivers. Offline mode blocks discovery; low-bandwidth mode permits an explicit refresh. --omit=optional retains local playback but omits AirPlay. Software RAOP tests do not establish compatibility with every physical or AirPlay 2 receiver.

On Alpine use a musl-native Node package; a glibc binary is not interchangeable. Alpine and other musl targets remain experimental until the selected CPU and runtime have repeatable execution evidence. On OpenRC, runit, a container, or any system without an accessible systemd user manager, the player, library and TUI remain usable. Background alarm scheduling is unavailable; RadioCLI does not substitute cron/at jobs with weaker occurrence or snooze guarantees.

Windows

Use Windows Terminal or PowerShell with a native Node 22/24 runtime and 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

Windows x86 has a Node 22 route; Node 24 no longer provides it. Windows ARM64 needs matching native binaries: the WinGet mpv recipe above is x64-only, while the Node LTS recipe and Scoop's mpv package have ARM64 routes. These catalogs do not establish runtime or audio verification on their own. Windows XP and older Windows versions below the standard runtime minimum have no legacy client.

WSL uses the Linux installation path and remains experimental. Its Linux audio path, user manager and graphical environment need separate verification; Windows package discovery does not provide Linux playback tools.

BSD And Additional Runtimes

Install a native Node 22+ runtime and matching npm first, then install the same npm package. These are package instructions, with verification status in the platform matrix. No new background alarm adapter is provided for these systems.

Setup detects FreeBSD pkg, OpenBSD pkg_add, pkgsrc pkgin, Haiku pkgman, and a distinct termux-pkg recipe that invokes Termux's pkg. For example:

radiocli setup --only=mpv --dry-run
radiocli setup --package-manager=termux-pkg --only=mpv --dry-run

Do not select the FreeBSD pkg recipe on Termux or illumos. Setup checks the host before invoking these recipes and uses root, sudo or doas where applicable. Termux's main FFmpeg package omits ffplay; enabling an X11 repository and its display/audio services remains a manual choice. Haiku's ffmpeg8_tools recipe does not resolve its Node runtime blocker. pkgsrc uses versioned FFmpeg/ffplay pairs, so setup reports that component as manual rather than guessing a package. On a minimal NetBSD installation, select the matching X11 base distribution set through the OS installation tools before installing mpv. See NetBSD's distribution-set instructions; the package manager cannot supply missing base-system X11 libraries itself.

The recorded BSD guests installed a local packed tarball into fresh projects, omitting the optional AirPlay sender. After providing the matching Node/npm/player prerequisites, a manual registry installation uses:

npm install -g --omit=optional @ciphore/radiocli

Player Paths And Constrained Sessions

Set an absolute executable path when the player is outside the standard search locations. The value is a single executable, with no shell or appended arguments:

RADIOCLI_MPV_PATH='/opt/Audio tools/mpv' radiocli doctor

PowerShell uses $env:RADIOCLI_MPV_PATH = 'C:\Audio tools\mpv.exe' before the command. The other overrides are RADIOCLI_FFPLAY_PATH, RADIOCLI_VLC_PATH and RADIOCLI_FFMPEG_PATH. Invalid explicit paths produce diagnostics instead of silently choosing another executable. Run radiocli alarm sync after changing the paths retained by native alarm jobs.

For SSH, use a terminal allocation such as ssh -t for the TUI, or use CLI/MCP commands and explicit headless playback. Browser, clipboard and terminal reopening depend on the actual desktop session. See troubleshooting for ASCII/color controls, offline caches, proxies, IPv6 and writable data directories.

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.

The required CI matrix covers Node 22/24 on Ubuntu, macOS and Windows with native x64/arm64 jobs and packed-install mpv checks. BSD guest jobs are opt-in/weekly. The platform matrix records actual results and the limits of those checks.

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.

Background alarms are unavailable without systemd user scheduling on Linux; 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.