CLI Usage

RadioCLI opens the full TUI by default:

radiocli

It also supports command mode for scriptable tasks:

radiocli doctor
radiocli doctor --json
radiocli setup
radiocli setup --dry-run
radiocli setup --mcp
radiocli mcp status
radiocli mcp repair
radiocli update --install
radiocli agent status
radiocli check
radiocli countries
radiocli search "japan hits"
radiocli import stations.m3u
radiocli export favorites.m3u
radiocli add-url <stream-url> [station name]
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 ~.

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, macOS 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 only on macOS, select receivers by opaque IDs returned from discovery, and never save a receiver passcode. 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.

Playlist Import And Export

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.

Direct Stream Adds

Use radiocli add-url when a public stream is known but not present in the provider directories:

radiocli add-url https://example.com/live.mp3 "Example FM"

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.