TUI Controls

RadioCLI keeps shortcuts at the bottom of the terminal. When playback is active, a compact live row sits above the shortcuts with station, cleaned track metadata, volume or mute state, and an active sleep timer.

Global Controls

Pause, mute, volume, and play/pause media-key control require the mpv backend. Because RadioCLI plays live radio rather than on-demand audio, resuming a paused station reloads its stream and discards buffered delayed audio. This returns to what the station is broadcasting now for imported and directory stations alike. When ffplay or VLC is active, RadioCLI keeps playback and station skipping available but labels interactive playback controls as limited and shows an Install mpv warning instead of pretending the control worked.

Screen Controls

Explore keeps an aspect-correct Braille world map in full, compact, and micro layouts. Compact windows always place stations beside the map, while true micro places the selected station below it. Long selected station and metadata lines scroll after a short pause in compact and micro layouts. Enable Reduce Motion to keep those lines truncated instead. ASCII mode substitutes plain characters for the map's decorative glyphs.

Press ? from any screen to open Help, a full reference of keybindings and : commands. In the command palette, Tab completes the command name.

Mouse and trackpad scrolling enables terminal mouse reporting only while Explore or an overflowing menu/list is active, leaving native scrollback available on other screens. Settings can disable mouse support completely. Keyboard controls and Explore's WASD movement remain available when a terminal or tmux setup does not pass mouse events through.

Alarms Workspace

Open Alarms from Overview; it is the item immediately before Settings. The list shows enabled state, schedule and timezone, station, next occurrence, and scheduler degradation. Choose the visible Create alarm row or press n for a blank alarm; press a from a selected/playing station to open a prefilled editor.

The editor covers:

• label, enabled state, primary station, one-time or recurring schedule, local date, segmented 24-hour time, weekday checklist, and IANA timezone
• independent alarm volume, fade-in seconds, automatic stop time, optional fallback station, and fixed local-speaker output
• missed-run grace, best-effort OS wake request, and Alarm Guard
• a next-occurrence preview, a no-state-change test tune, Save, and Cancel

Time is a segmented digital control whose active hours or minutes are highlighted in the current display color. Use Up and Down to change hours, press Enter to advance to minutes, adjust again, then press Enter to finish. Left and Right still move directly between segments. Weekdays open as a nested Monday-through-Sunday checklist; move with Up and Down, toggle any combination with Space, and press Enter to confirm. Bounded values such as volume, fade, stop-after, and missed-run grace use arrow-adjustable controls instead of requiring text replacement. Free-form values such as label and timezone retain normal text editing. The station picker draws from the current station, favorites, imports, recents, and stations already used by alarms. Saving persists the definition locally and synchronizes the native OS job; if that setup is degraded, the alarm remains visible with a repair marker. Press r from the list to retry all registrations.

Choose Verify alarm setup at the bottom of the alarm list to rehearse the complete path on the current machine. RadioCLI installs and queries a disposable native scheduler job, opens the saved terminal through an authenticated loopback handshake, verifies dismiss/snooze connectivity, acquires and releases sleep protection, raises and restores system output, and plays a three-second sample from the next configured alarm. The disposable job is removed before the report finishes.

The report separates hard blockers from limitations. A wake request can be accepted by the scheduler while still depending on hardware, lid, power, login-session, and administrator policy. Run Verify again after changing the terminal, playback backend, audio device, OS permissions, or power settings.

t on the alarm list test-tunes only the primary station and does not fire the alarm or change run history. The CLI's radiocli alarm test is a separate, bounded end-to-end alarm preview.

When an alarm starts, RadioCLI publishes an authenticated local control session. If the TUI is open it presents the high-contrast ringing screen; if you open the TUI after playback began, press ! from any screen. Space stops playback and snoozes for 10 minutes. Enter transfers the station into RadioCLI's normal interactive player and opens Playing with its visualizer and controls. b returns to the app while the detached alarm continues. The TUI polls for concurrent active alarms and lets you select the exact one before acting.

The terminal does not need to remain open after a native job is registered. Playback still requires a powered-on machine, a logged-in interactive audio session, working local speakers, and a reachable stream. Alarm Guard prevents idle sleep but consumes power and cannot override a closed lid, explicit sleep, hibernate, shutdown, or OS policy. Full details are in Reliability.

Alarms are experimental beta functionality. Use a secondary device as the primary alarm whenever timing is critical. See the dedicated Alarms guide for setup, verification, delivery, and repair.

Command Palette

Useful command entries:

:search lagos jazz
:country japan
:codec MP3
:language spanish
:bitrate 128
:clear
:volume 60
:mute
:favorite
:sleep 15
:sleep off
:timeout 15
:skip off
:location on
:doctor
:resume on
:ascii on
:motion on
:background on
:help
:learn previous
:learn play
:learn next
:keys reset
:airplay
:airplay-code 1234
:map
:library
:stats
:settings
:import https://example.com/live.mp3
:import https://example.com/live.mp3 Example FM
:export radiocli-backup.json
:restore radiocli-backup.json
:stop

:import adds a custom station from a direct HTTP(S) stream URL and discovers available HTTP/ICY metadata automatically. Use it when a station is absent from search or an open-source radio directory, including direct streams from networks such as iHeartMedia. Find the station's direct stream URL rather than its ordinary website or web-player page. Newly imported stations appear directly below favorites and above recently played stations in the Library.

:restore is reserved for restoring a full RadioCLI JSON backup containing preferences and library data.

Display And Compatibility Modes

Settings includes toggles for terminals and devices that need them, each also available as a command. These choices are saved in your local library:

• Resume last station on launch (:resume on) re-tunes your most recent station when RadioCLI starts, like a radio powering back on.
• Transparent background (:background on) drops the dark panel fill so light-themed terminals keep their own background.
• ASCII-safe display (:ascii on) maps braille, block, and box-drawing glyphs, borders, and decorative punctuation to ASCII. International station names and metadata remain intact; this is not a transliteration setting.
• Reduce motion (:motion on) freezes the receiver and loading animations and keeps long lines truncated instead of scrolling.

RadioCLI retains its Unicode receiver display on terminals that support it, including UTF-8 sessions over SSH. Locale detection checks the first non-empty value in LC_ALL, LC_CTYPE, then LANG. A bare C or POSIX locale selects ASCII decoration; UTF-8 locales such as C.UTF-8 do not. SSH alone does not change the display mode.

Environment variables override rendering for that launch without rewriting saved appearance settings:

Detected 16-color terminals retain their own background; 256-color and truecolor terminals can use the dark receiver panels. NO_COLOR, screen-reader mode, and TERM=dumb take precedence over FORCE_COLOR.

For one launch in a POSIX shell:

RADIOCLI_ASCII=1 RADIOCLI_DISABLE_ANIMATION=1 radiocli

In PowerShell, set the variables for the current shell before launching:

$env:RADIOCLI_SCREEN_READER = '1'
radiocli

Screen-reader mode keeps keyboard navigation, station and playback labels, selection, and command entry available. Decorative receiver frames are omitted, and long labels are exposed as text without a scrolling marquee.

The TUI requires interactive keyboard input, including with TERM=dumb. Use CLI commands such as radiocli doctor --json and radiocli search "jazz" in pipelines or scripts. For display problems, see Troubleshooting; runtime and optional feature coverage is listed under Platforms.

Source-List Queues

When you tune a station from Library, Explore, Search, Countries, or Nearby, that list becomes the playback queue. Previous/next keeps moving through that source list from any screen until you tune from another list.

Learned Media Keys

Hardware media keys depend on the OS and terminal. RadioCLI recognizes common F7/F8/F9 sequences, Kitty media-key codes, modified-arrow sequences, comma/dot transport fallback, and learned custom bindings. Previous/next media actions are app-level; play/pause requires mpv.

Learn keys from Settings or with :learn previous, :learn play, and :learn next; clear them with :keys reset.

Location behavior is covered in Privacy and Security.

On macOS and opted-in native Linux, Settings opens an experimental AirPlay receiver picker using Bonjour or Avahi respectively. Change Audio output to AirPlay with o, open AirPlay with a or :airplay, and choose a visible receiver. If a station is already playing, RadioCLI moves it to the selected receiver immediately; switch Audio output back to This device (mpv) to leave AirPlay. RadioCLI does not auto-pick a receiver. AirPlay is a current-session output: restarting RadioCLI returns to automatic local playback while remembering the last receiver for the next manual switch. If the receiver asks for a code, RadioCLI opens the AirPlay Code screen; you can also press c from AirPlay settings or use :airplay-code 1234.

On Linux, run radiocli setup --airplay first. AirPlay settings and suggestions are hidden until you opt in, and remain hidden on unsupported platforms. An opted-in installation with missing dependencies shows Setup required. Temporary service or receiver failures stay visible with an explanatory message. macOS keeps its existing picker and setup defaults.

Linux discovery starts only when you open or refresh the picker. Offline mode blocks it; low-bandwidth mode still permits an explicit refresh. Receiver selection is required in each process, including when a previous choice was saved. Pause remains a local mpv feature; AirPlay supports volume and mute.

On eligible Omarchy Quattro desktops, the application-owned MPRIS bridge lets hardware media keys and the optional shell media widget control the current station queue. It also works when MCP is disabled. Use radiocli media-controls [auto|on|off] and restart the active session to change that policy, or set RADIOCLI_DESKTOP_MEDIA=off for an environment override. Existing learned terminal media-key sequences remain available.