# Install (/docs/getting-started/install) ## Choose Your Install [#choose-your-install] Use npm on macOS, Linux, or Windows when Node.js 22 or newer is already installed: ```bash 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: ```bash 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 [#upgrade-an-existing-installation] RadioCLI preserves preferences, favorites, history, alarms, and agent settings outside the installed package. Check or install the latest release with: ```bash 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 [#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 [#quickest-try-it-with-npx] If you already have Node.js 22+, run RadioCLI without installing anything: ```bash 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 [#recommended-macos-with-homebrew] Homebrew is the lowest-friction macOS path. The tap formula installs RadioCLI, Node.js, `mpv`, and FFmpeg through Homebrew: ```bash brew install ciphore/tap/radiocli radiocli ``` Run `radiocli doctor` any time you want to verify local playback readiness. ## Universal npm Install [#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. ```bash 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. ```text 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: ```bash 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: ```bash 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: ```bash 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 [#linux] On Debian/Ubuntu: ```bash sudo apt install mpv npm install -g @ciphore/radiocli radiocli setup radiocli ``` Other common Linux packages: ```bash 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: ```bash npm install -g @ciphore/radiocli radiocli setup radiocli ``` ## Windows [#windows] Use Windows Terminal or PowerShell with Node.js 22 or newer and native `mpv`: ```powershell 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: ```powershell 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 [#optional-ffplay-fallback] Install FFmpeg separately only if you want `ffplay` fallback support: macOS/Linux: ```bash brew install ffmpeg # macOS sudo apt install ffmpeg ``` Windows: ```powershell 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 [#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](../reliability.mdx) for the platform matrix and Alarm Guard tradeoffs. ## Local Checkout [#local-checkout] ```bash 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: ```bash npm run dev ``` ## Built Binary [#built-binary] After a local build, the same command-mode actions can be run directly: ```bash node dist/cli.js check node dist/cli.js search "lagos talk" ``` ## Data Paths And Migration [#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](./cli.mdx) or [learn the TUI controls](./tui-controls.mdx).