tui run for viewers

Command Type

built-in

Signature

> tui run {flags} (hook)

Flags

• --dialog, -d: Show a floating, draggable, resizable popup on the alternate screen.
• --size, -s {list<int>}: Popup [width height] with --dialog. Default: 3/4 of the terminal.
• --refresh, -r {duration}: How often to re-run the hook (e.g. 1sec).
• --no-mouse: Disable mouse capture.

Parameters

• hook: Hook whose output replaces the data list. Used with --refresh.

Input/output types:

Examples

Pick a file

> ls | tui label --title "files" | tui table | tui run | get selected.name

Refresh a file list every second, in a popup

> ls | tui table | tui run --dialog --refresh 1sec { ls }

Read a text box by id after submit

> tui textbox --id name | tui run | get values.name

Notes

Interactive keys:

• Tab / Shift+Tab: move focus between widgets
• [ / ] or Ctrl+Tab: switch tabs; 1-9: jump to a tab
• Arrows, hjkl, PageUp/PageDown, Home/End: move in lists; scroll logs
• Space: check a row in a --multi list
• Type in a focused search box or text box; q is a character there
• Mouse: click to focus/select, scroll, drag split handles and dialog chrome
• Enter: submit the focused widget's selection and return a record
• q / Esc (when not typing) or Ctrl+C: quit

The result is {action, focused, selected, page, values, rows, live}. action is submit or quit; selected is the focused widget's selection (a table row, checked rows with --multi, a text box's text, ...); values holds every widget's state by id, e.g. values.table-0.index.

A closure runs as a hook with the state record as $in: its output replaces the data list, {action: submit, selected: ...} ends the TUI, null does nothing. --refresh 1sec { ls } re-runs it on that interval; without --refresh it runs once at start. --dialog opens a floating popup on the alternate screen; --size [70 20] sets its size.

To render without a terminal, or to replay keys in a test, use tui debug.