RadioCLI brings live radio to your terminal. Browse stations around the world,
save favorites, and listen through mpv—without an account or cloud library.
Built with Ink, React, and the Radio Browser directory.
- Discover stations through Explore, Search, Countries, or approximate-location Nearby.
- Listen with a receiver-style Now Playing screen, live metadata, sleep timer, diagnostics, and selectable visualizers.
- Keep favorites, recents, imports, track history, and listening stats on your machine.
- Create one-time or recurring radio alarms from the TUI, with native background scheduling, station fallback, missed-run grace, snooze, and optional Alarm Guard.
- Move through the exact station list you tuned from with previous and next controls.
- Use
mpvfor complete playback control, withffplayand VLC as limited fallbacks. - Resize freely: full, compact, and micro layouts preserve navigation and essential controls; Explore retains its interactive world map at every usable size.
macOS with Homebrew:
brew install ciphore/tap/radiocli
radioclimacOS, Linux, or Windows with npm:
npm install -g @ciphore/radiocli
radiocli setup
radiocliRadioCLI requires Node.js 22 or newer. The Homebrew formula installs mpv and
FFmpeg. After an npm install, radiocli setup detects the operating system and
package manager, lets you choose mpv, FFmpeg, and VLC, installs the selected
native tools with branded progress feedback, and verifies playback readiness.
See the installation guide for Windows, Linux distributions, AirPlay prerequisites, and fallback players.
These recordings come from the built TUI. Generate them locally with
npm run demo:assets.
| Key | Action |
|---|---|
← / → or Tab / Shift+Tab |
Switch screens |
↑ / ↓ or n / p |
Move the selection |
Enter |
Open or tune the selection |
space or F8 |
Pause or resume with mpv |
, / . or F7 / F9 |
Previous or next station |
+ / - |
Change volume |
f |
Save or remove a favorite |
? |
Open all shortcuts and commands |
q or Ctrl+C twice |
Quit cleanly |
The footer always shows controls for the current screen. Press : to open the
command palette. The TUI controls guide
covers filters, playback, media-key learning, AirPlay, and every command.
RadioCLI can also be controlled by local coding agents. Run radiocli setup
and opt into MCP, or use radiocli setup --mcp, to configure detected Codex,
Claude, OpenCode, Cursor, Gemini, VS Code/Copilot, and Orca-backed runtimes
automatically. From the TUI, open Settings → Agent control & MCP and turn on
Allow local agent control for the same one-step setup—no terminal command is
required. The same actions are
available to non-MCP harnesses through radiocli agent and radiocli alarm:
search and play stations, browse recents/favorites/nearby stations, favorite the
current station, inspect listening stats, create and control alarms, control
macOS AirPlay, change the receiver look, or run a user-configured completion
preset. Codex Voice can invoke those same typed MCP tools. Agent playback opens
the normal RadioCLI TUI in a terminal window by default on macOS, Windows, and
Linux. Interactive setup explains that macOS may require the agent host to approve
a one-time Automation prompt; users can explicitly opt into headless playback.
Scheduled alarms remain isolated and always use local output rather than
unattended AirPlay. See the
CLI guide.
radiocli # Start the TUI
radiocli check # Check providers, playback tools, and the local store
radiocli doctor --json # Create a redacted support report
radiocli search "japan hits"
radiocli countries
radiocli import stations.m3u
radiocli export favorites.m3u
radiocli add-url <stream-url> [station name]
radiocli alarm list
radiocli alarm doctor
radiocli update --install # Upgrade and repair enabled MCP registrationsExisting installations keep their library and preferences when upgraded. Use
radiocli update to inspect the detected Homebrew, npm, pnpm, or Bun command,
or radiocli update --install to run it. MCP registrations use an
upgrade-stable launcher so versioned package paths do not break them. On
Windows this is a shell-free Node command; on Unix it uses the radiocli shim.
Run radiocli mcp status to inspect registrations and radiocli mcp repair
after moving an installation or when an agent client reports a stale server;
fully quit and reopen agent clients after enabling, repairing, or upgrading.
Until that restart, even a newly created task in an already-running client will
not have RadioCLI's tools and may incorrectly fall back to browser playback.
RadioCLI imports .m3u, .pls, and .xspf playlists. It exports favorites
and imported streams as .m3u.
Alarms are experimental beta functionality and live under Overview, immediately before Settings. Saving an enabled alarm registers it with launchd on macOS, a systemd user timer on Linux, or Task Scheduler on Windows, so the terminal does not need to remain open. When it fires, RadioCLI reopens the saved supported terminal and shows the ringing screen. Enter transfers the station into normal interactive playback; Space stops it and snoozes for 10 minutes. If a RadioCLI TUI is already open, that instance shows the controls instead. The computer must still be powered on with a logged-in interactive audio session; wake timing depends on hardware and OS power policy. See the CLI guide and reliability notes before relying on an alarm for something critical. Use a secondary device as the primary alarm for safety-critical, medical, travel, or emergency timing. See the dedicated Alarms guide for the full workflow.
The Verify alarm setup row performs a disposable native-scheduler registration, an authenticated terminal/control handshake, sleep-inhibitor and system-volume checks, and a short sample from the next configured alarm. It cleans up the temporary job and reports hard blockers separately from hardware- or policy-dependent wake limitations.
See the CLI guide for all arguments and examples.
RadioCLI prefers mpv because it handles redirects, HLS, real-world codecs,
ICY metadata, and interactive controls reliably. ffplay and VLC can keep a
stream playing when mpv is unavailable, but the UI labels their controls as
limited.
Station providers use mirror fallback, bounded caches, and stale-cache recovery. Playback waits for backend readiness, applies tune timeouts, and can skip broken streams. Corrupt library and cache files are backed up instead of silently overwritten.
Scheduled playback retries the primary station once, then tries an optional
fallback. A missed-run grace window controls catch-up after sleep or logout.
True fade-in requires mpv; ffplay and VLC start audibly at the configured
target volume. Scheduled alarms always use local speakers, never unattended
AirPlay.
On macOS, an npm or source installation is executed by Node, so System Settings
may identify its background item as node. Showing RadioCLI as the providing
application requires a future signed macOS app bundle with a bundled helper;
changing a launchd label cannot safely relabel the executable.
Read the reliability notes for failure handling and troubleshooting.
RadioCLI does not require an account, proxy audio, or upload your listening history. Favorites, recents, imports, settings, alarms, track history, and activity stay in a local JSON library. Full JSON library backups include alarm definitions, while native scheduler registrations, runtime health, Alarm Guard state, and authenticated loopback-control tokens remain machine-local.
Nearby contacts ipapi.co only when you open that screen, then uses an
approximate location to sort the local station atlas. Disable the lookup with
l, Settings, or :location off.
Favoriting a Radio Browser station sends a best-effort public directory vote by default. Turn off Share favorite votes with Radio Browser in Settings to keep favorites local-only.
See Privacy and security for the complete data-flow description.
src/ui— screens, input, layout, and terminal renderingsrc/providers— station directories, resolution, and cachessrc/player— playback backends, metadata, and AirPlaysrc/alarms— schedules, native registration, Alarm Guard, and active controlssrc/storage— local library persistence and migrationapps/docs— documentation website and manual
More detail lives in the architecture guide and design notes.
git clone https://github.com/Ciphore/RadioCLI.git
cd RadioCLI
npm ci
npm run verify
npm run devnpm run verify checks types, lint, tests, the production build, and package
contents. Playback and live-data smoke tests are available separately because
they contact public services or start a local player.
Contributions are welcome. Start with CONTRIBUTING.md, and
include radiocli check output with playback reports.
Run the documentation site locally with npm run docs:dev.