tui for viewers

Command Type

built-in

Signature

> tui {flags}

Input/output types:

Examples

List TUI subcommands

> tui

Notes

You must use one of the following subcommands. Using this command as-is will only produce this help message.

Builders (tui table, tui split, ...) append widgets to a tui value. tui run shows it and returns one record: {action, focused, selected, page, values, rows, live}, where values holds every widget's state by id. tui debug returns the same record plus the painted screen and the resolved layout, for scripts and tests.

Data: a value piped into a builder is the shared data list. Builders never read a stream: a list stream, a range, or an external command's output is kept in the tui value and read while the TUI runs, so its rows appear as they are produced (1.. | each {|n| sleep 1sec; $n} | tui log). A stream keeps its newest 100k rows (older rows are dropped in batches, so up to 12.5k more may show). When the TUI closes, a stream still producing is stopped: an external command piped straight into a builder at once, and one behind other commands (^tail -f app.log | lines | tui log) at once in an interactive shell, elsewhere the next time it writes. Nushell code in a stream (an each closure) finishes the row it is on, and what it prints while the TUI runs lands on the TUI's screen. A tui value saved with let reads its stream the first time it runs; if that run read it to the end, later runs show the same rows. A widget can have its own rows with --data, or by piping into it inside a container's child list: tui split [(ls | tui table) (ps | tui table)]. A widget can also follow the highlighted row of a table, tree, or select. A closure on tui table, tree, log, progress, or label turns that row into what the widget shows, and --from <id> picks which one to follow; without it the widget follows the focused one, else the nearest, else one on another tab page, but never one that follows it back. --from without a closure shows the row itself. A widget with nothing to follow is an error when the TUI starts, and --data cannot be combined with --from or a closure.

Hooks: tui bind, menu actions, tui button, --on-select, and the tui run refresh closure all receive the state record and may return nothing, a new data list, or {action: submit|quit, selected: ...}. A new data list replaces the shared data for the rest of the run: a piped stream no longer adds to it.

Layout: tui split --sizes [30% 1fr] arranges children; tui box groups them with a border; tui tab makes a page. Bordered widgets take --title to rename their border (tui table --title files shows files (12)); tui label --titlebar fills the bar at the top. Colors come from $env.config.tui; --border on a widget or $env.config.tui.border_type picks its border lines by table --theme name (rounded, double, heavy, ...).

Subcommands: