# CLI Usage (/docs/getting-started/cli) RadioCLI opens the full TUI by default: ```bash radiocli ``` It also supports command mode for scriptable tasks: ```bash 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 [station name] radiocli alarm list radiocli alarm doctor ``` `radiocli export` writes `radiocli-favorites.m3u` when no output path is provided. ## Health Check [#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 [#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 [#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: ```bash 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 [#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 [#direct-stream-adds] Use `radiocli add-url` when a public stream is known but not present in the provider directories: ```bash radiocli add-url https://example.com/live.mp3 "Example FM" ``` ## Alarms And Scheduled Radio [#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`: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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](../reliability.mdx) for the platform matrix and operational limits. For interactive keyboard behavior, continue to [TUI Controls](./tui-controls.mdx).