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. When only ffplay 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.

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 review, 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
:stop

Display And Compatibility Modes

Settings includes toggles for terminals and devices that need them, each also available as a command:

• 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. RadioCLI also honors the NO_COLOR convention automatically.
• ASCII-safe display (:ascii on) maps braille, block, and box-drawing glyphs to ASCII for terminals and fonts without those glyphs.
• Reduce motion (:motion on) freezes the receiver and loading animations to save CPU and bandwidth over SSH and on low-power devices.

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, Settings opens a dedicated AirPlay receiver picker for Bonjour receivers. 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.