CLI Usage

RadioCLI opens the full TUI by default:

radiocli

Everyday Listening

Start listening from your shell without opening a full-screen interface or enabling MCP. The same play command starts and continues listening:

radiocli play jazz
radiocli pause
radiocli play
radiocli stop

These eight commands cover everyday listening:

radiocli help shows this short guide. radiocli help --all groups the full command list by purpose, and radiocli help play explains one command. previous, mute, unmute, and resume remain available when you need them.

play starts a background player and returns to your prompt. If the TUI is already open, commands control that player instead. The CLI uses the same library, playback backends, metadata, and listening history as the TUI. stop closes background playback; use play to start again. Pause, volume, and mute depend on backend capabilities; mpv provides full controls.

Station selection accepts a saved preset, a station name, or an exact provider:id. Saved presets and names are checked before the public directory. A unique match plays immediately; multiple matches offer a numbered chooser in an interactive terminal. In scripts, ambiguous names fail with matching IDs so you can select the exact station. play with no argument resumes a paused station, leaves playing audio uninterrupted, or restarts the selected station after stopping. It preserves that station's queue. When no station is selected, it starts your most recent station.

radiocli play --favorites
radiocli play --favorites --random
radiocli play --recent --pick
radiocli play --popular
radiocli play --country JP
radiocli play "Groove Salad" --keep-playing

Choose one queue flag: --favorites, --recent, or --popular. The longer --source form still accepts recent, favorites (also favorite), popular, or country. Country queues require --country with a two-letter code. Explicit queue or filter options select a station anew; they do not resume the current selection. --random selects from the chosen queue; --keep-playing preserves an already playing or paused station. Next and previous follow the selected search or library queue, wrapping at its ends. Ordinary playback commands do not dismiss or modify alarms, and play is refused while an alarm occurrence is active.

Search And Choose

radiocli search jazz --pick
radiocli search jazz --country US --language english --limit 10
radiocli search ambient --codec MP3 --min-bitrate 128
radiocli countries --limit 20

Search shows a table with station name, country, audio quality, and a * for favorites. --pick lets you enter a result number to start playback. Enter q, press Enter on an empty selection, or press Ctrl+C to cancel. The chooser preserves terminal scrollback and retries invalid numbers.

Search and station-name playback accept --country, --language, --codec, --min-bitrate, and --limit. Limits range from 1 through 100; search defaults to 20. An empty result includes a suggestion to broaden the query. Station names beginning with a dash can follow --, for example radiocli search -- "-station name".

Now Playing

radiocli now
radiocli now --watch
radiocli status --json

The compact view includes station, current track when supplied by the stream, playback state, audio output, volume, and mute status. status is an alias for now. --watch refreshes one terminal line when the displayed information changes. Ctrl+C exits the view while playback continues. Screen-reader mode prints changed states on separate lines instead of rewriting a line.

Favorites, History, And Presets

radiocli favorite                        # save the active station
radiocli favorite "Groove Salad"
radiocli favorites --pick
radiocli recent --pick
radiocli unfavorite "Groove Salad"
radiocli stats

Favorites and recents accept --limit and --pick. Stats shows listening time, sessions, station count, streaks, and your most-listened station.

Presets give stations short names that are easy to remember and complete:

radiocli preset save work                # use the active station
radiocli preset save evening "Groove Salad"
radiocli play work
radiocli presets                         # also: radiocli preset list
radiocli preset remove evening

Preset names are case-insensitive and contain 1–40 letters, numbers, hyphens, or underscores, starting with a letter or number. Saving an existing name replaces its station. Removing a preset removes only the shortcut. Up to 200 presets are stored in the local library and included in JSON backup/restore. M3U export continues to contain favorites and imported stations.

Output And Scripts

Listener commands support consistent output options:

These options apply to playback, search, countries, library, preset, stats, and now-playing commands. Existing setup, alarm, update, and agent commands retain their own documented options.

radiocli search jazz --json
radiocli favorites --plain
radiocli play radio-browser:STATION_ID --no-input --quiet
radiocli now --json
radiocli help play
radiocli help --all

Output automatically becomes plain when piped. Search, favorites, and recents use five TSV columns: provider:id, name, country, codec, and bitrate. Country rows retain code, station count, and name. Preset rows use name, station ID, and station name. Now-playing and stats use key/value TSV rows. Control results use ok or error followed by the message. Empty lists have no TSV rows.

JSON search/library results are arrays with id, name, country, countryCode, codec, bitrate, language, tags, and favorite. Now-playing JSON is the session snapshot, or null when no player is active. Control results include ok, message, and the session status when available. --pick and --watch require an interactive terminal and cannot be combined with JSON, plain, quiet, or no-input mode. Successful commands exit with 0; errors exit with 1; cancelling a picker or watch with Ctrl+C exits with 130.

Shell Completion

Load completion for your shell, then add the same line to its profile if you want it available in new sessions:

# Bash
source <(radiocli completion bash)

# Zsh, after compinit
source <(radiocli completion zsh)

# Fish
radiocli completion fish | source

# PowerShell
radiocli completion powershell | Out-String | Invoke-Expression

Completion suggests commands, command-specific flags, common filter values, and saved preset names. It does not query public station directories or change your shell configuration. Misspelled commands suggest a likely correction without executing it.

Other Commands

radiocli doctor
radiocli setup
radiocli setup --dry-run
radiocli setup --mcp
radiocli mcp status
radiocli mcp repair
radiocli update --install
radiocli agent status
radiocli check
radiocli import https://example.com/live.mp3
radiocli import stations.m3u
radiocli export favorites.m3u
radiocli alarm list
radiocli alarm doctor

radiocli export writes radiocli-favorites.m3u when no output path is provided.

Health Check

Use radiocli doctor after installation to confirm whether mpv or ffplay is available, whether playback controls are full, limited, or missing, and to print the recommended native install command for your OS. Doctor also prints the resolved mpv path, how RadioCLI discovered it, its version, and whether it can actually launch. mpv is the full-control backend; ffplay is reported as fallback playback with limited controls. Use radiocli doctor --json for a machine-readable support report; paths under your home directory are redacted to ~.

Doctor also separates Omarchy release evidence, terminal prerequisites, desktop media policy, user-bus and audio readiness, scheduling, and AirPlay prerequisites. It does not browse receivers, open a terminal, or register an MPRIS player. An available tool is not proof of audible output or a working receiver.

Configure Linux desktop media controls with:

radiocli media-controls            # show saved and effective policy
radiocli media-controls auto       # packaged Quattro local desktop
radiocli media-controls on         # opt in on another Linux desktop
radiocli media-controls off
RADIOCLI_DESKTOP_MEDIA=off radiocli # override for this process

Restart active sessions after changing the saved setting. Other platforms retain their existing media-key behavior; this setting selects the Linux MPRIS bridge.

Use radiocli check when debugging playback or provider issues. It reports local store paths, playback backends, and provider health. Include that output when filing playback issues.

Guided Setup

Use radiocli setup after an npm installation to select and install native playback tools. It detects the host package manager, skips tools that are already available, asks for confirmation before making system changes, and runs the doctor verification when installation finishes.

Use --yes for the recommended defaults, --all --yes for every supported player, --only mpv,ffmpeg for an explicit selection, or --dry-run to print the exact commands without running them. Linux elevation is limited to the native package-manager command; the RadioCLI process itself is not elevated.

Interactive setup also asks whether to enable local agent control. Choose yes, or use radiocli setup --mcp, to register RadioCLI as a user-level stdio MCP server in every detected supported harness. Codex and Claude are configured through their own CLIs; OpenCode, Cursor, Gemini CLI, and VS Code/Copilot Agent Host use their documented user-level JSON/JSONC files without discarding comments; and Orca can use the integrations exposed through its configured agent runtimes. A portable configuration is also written for other MCP clients. Use --no-mcp or radiocli mcp disable to reverse those registrations; playback tools and alarms are unaffected.

If you prefer not to run setup commands, open Settings → Agent control & MCP in the RadioCLI TUI and turn on Allow local agent control. That single control installs detected MCP integrations and also removes them when turned off. The repair row immediately below it refreshes registrations after an upgrade or move.

On Windows, run MCP setup from native Windows RadioCLI to configure the Windows Codex/ChatGPT host. WSL is a separate Linux host with its own home directory and MCP configuration; run setup inside WSL as well only if you use agents there.

radiocli mcp status reports the upgrade-safe launcher and whether file-based client registrations are configured, missing, or stale. radiocli mcp repair idempotently refreshes every detected registration and is safe to run after an upgrade or installation move. Restart open agent clients afterward. Agents can use the read-only radio_update_status tool to report installed/latest versions and the appropriate package-manager command, but RadioCLI never installs an update through MCP without the user running or approving an update path.

Local Agent And MCP Control

The MCP server exposes typed tools for status, discovery, playback, favorites, listening stats, appearance, alarms, experimental macOS/Linux AirPlay, and configurable completion actions. This includes creating, editing, enabling, disabling, listing, synchronizing, and explicitly confirmed alarm removal, plus dismiss, snooze, keep-playing, and interactive handoff for a ringing occurrence. It accepts only saved stations or opaque station IDs returned by RadioCLI discovery tools; agents cannot supply arbitrary stream URLs.

Codex Voice uses the same MCP tools, so spoken requests such as “create a weekday alarm for 7:30 AM on this station,” “snooze that for ten minutes,” or “send this to the Office speaker” do not need a separate voice integration. Alarm times remain explicit typed schedules, and the agent must ask for a timezone or other materially missing detail instead of guessing. Alarm deletion requires an exact ID and explicit confirmation.

The equivalent shell interface is useful for harnesses without MCP:

radiocli agent search "late night jazz"
radiocli agent play radio-browser:STATION_ID
radiocli agent favorite                 # favorites the active station
radiocli agent browse favorites
radiocli agent stats
radiocli agent airplay list
radiocli agent airplay select RECEIVER_ID
radiocli agent airplay local
radiocli agent done                     # runs the completion preset

Harnesses without MCP can use the existing complete radiocli alarm command set for alarm creation and control. AirPlay commands are available on macOS and native Linux after radiocli setup --airplay, select receivers by opaque IDs returned from discovery, and never save a receiver passcode. Agent and headless controls respect the same Linux opt-in as the TUI; a saved receiver or installed dependency does not enable it. Scheduled alarms continue to use local speakers; selecting AirPlay affects only interactive playback and cannot silently reroute an unattended alarm.

When playback is closed, agent playback opens the normal RadioCLI TUI on Now Playing by default on macOS, Windows, and Linux. On macOS, Apple requires the agent host to approve its own one-time Automation request before it can control Terminal; RadioCLI cannot pre-grant that consent. Use radiocli setup --mcp --headless-agent or change the Agent control preference in Settings only when external terminal windows are not wanted. Commands from multiple agents are serialized. Explicit actions are idempotent, and a completion preset with ifPlaying: keep lets the first finishing agent start music while later completions leave it alone. There is deliberately no task registry, implicit goal, automation, reminder, or monitoring task: the agent calls the chosen action only when its current task is complete unless the user explicitly requests one of those separate mechanisms.

radiocli agent stop controls only ordinary playback. It never dismisses, snoozes, edits, or stops an alarm; new interactive playback is refused while an alarm occurrence is active.

Custom Station And Playlist Import

RadioCLI imports .m3u, .pls, and .xspf playlists, including nested local playlists. Imported stations are treated as first-class playlist stations and can be exported together with favorites as .m3u.

Use radiocli import with a direct HTTP(S) stream when a station is missing from search or from the open provider directories. This is especially useful for networks such as iHeartMedia whose stations may not be available to open-source radio directories. Look up the station's direct stream URL—not merely its website or player page—and import it:

radiocli import https://example.com/live.mp3

RadioCLI makes a short, bounded request for HTTP and ICY headers and uses any published station name, homepage, codec, bitrate, and HLS status. Supply a name only when the stream does not publish one or when you want to override it:

radiocli import https://example.com/live.mp3 "Example FM"

The submitted stable URL is retained instead of temporary signed redirects. Imports are stored newest first and displayed after favorites but before recently played stations. Metadata availability varies by broadcaster, so details that a stream does not publish cannot always be discovered automatically.

Alarms And Scheduled Radio

The TUI is the primary alarm interface, but every runtime operation is also available under radiocli alarm. A station argument uses the provider:id key printed in the first column of radiocli search:

radiocli search "morning jazz"
radiocli alarm add \
  --station radio-browser:STATION_ID \
  --time 06:00 \
  --days weekdays \
  --timezone America/Los_Angeles \
  --label "Weekday jazz" \
  --volume 70 \
  --fade 30s \
  --stop-after 90m \
  --grace 15 \
  --wake

The station must already exist in favorites, imports, or recents. Recurring times use 24-hour HH:mm, ISO weekdays 1 through 7 mean Monday through Sunday, and the timezone must be an IANA name. --days accepts daily, weekdays, weekends, or a comma-separated set such as 1,3,5.

A one-time alarm requires an absolute ISO-8601 minute with Z or an explicit offset. Seconds must be zero; an ambiguous local timestamp is deliberately not accepted:

radiocli alarm add \
  --station radio-browser:STATION_ID \
  --once 2026-08-24T06:30:00-07:00 \
  --label "Monday special" \
  --volume 65 \
  --stop-after 1h

Creation options are:

• schedule: --once ISO, or --time HH:mm with optional --days and --timezone
• identity: required --station provider:id, optional --label and --disabled
• playback: --volume 0-100, --fade 30s|1m, --stop-after 60m|2h, and --fallback provider:id
• reliability: --grace 0-10080, --wake, and --guard

List, inspect, and modify alarms with:

radiocli alarm list
radiocli alarm list --json
radiocli alarm show ALARM_ID
radiocli alarm edit ALARM_ID --time 07:15 --days weekends
radiocli alarm edit ALARM_ID --fallback radio-browser:OTHER_ID
radiocli alarm edit ALARM_ID --clear-fallback --no-wake --no-guard
radiocli alarm enable ALARM_ID
radiocli alarm disable ALARM_ID
radiocli alarm remove ALARM_ID

edit accepts --label, --station, every schedule and playback value option, --grace, --wake / --no-wake, --guard / --no-guard, and --clear-fallback. Use the separate enable and disable commands for enabled state. Switching a one-time alarm back to recurring requires --time; changing only its days or timezone is rejected.

Saving an enabled alarm installs its next occurrence in the native scheduler. The terminal can close after registration. Use these commands to validate or repair the machine-local integration:

radiocli alarm doctor
radiocli alarm doctor --json
radiocli alarm status
radiocli alarm sync
radiocli alarm test ALARM_ID

doctor reports scheduler, sleep-inhibitor, Guard, and active-session health. status returns the detailed JSON state. sync rebuilds native registrations from the local library, which is useful after restoring a backup, changing the host timezone, updating or moving a source checkout, or repairing OS scheduler state. test performs a real, bounded playback preview; it can make sound and stops automatically if the preview cannot complete safely.

While one or more alarms are playing, control an exact occurrence with:

radiocli alarm status
radiocli alarm dismiss --alarm ALARM_ID --occurrence 2026-08-24T13:30:00.000Z
radiocli alarm snooze 10 --alarm ALARM_ID
radiocli alarm keep-playing --alarm ALARM_ID

The selectors are optional when exactly one alarm is active. If multiple alarms are playing, add --alarm and, when necessary, --occurrence.

Alarm Guard is separate from the OS wake request. --wake asks a capable scheduler to wake the machine; it is currently mapped to Windows Task Scheduler and remains subject to hardware and power policy. --guard starts a machine-local helper immediately and prevents idle sleep until the next occurrence, which consumes battery or mains power:

radiocli alarm guard start ALARM_ID
radiocli alarm guard status
radiocli alarm guard stop ALARM_ID
radiocli alarm guard stop

Guard cannot power on a shut-down machine or override explicit sleep, hibernate, a closed-lid policy, logout, or other OS policy. See Reliability for the platform matrix and operational limits.

For interactive keyboard behavior, continue to TUI Controls.