TUI concepts

Not every tool is a good CLI. Some interactions are inherently stateful and visual in a way that a command-plus-exit model handles poorly. Understanding the three interaction models helps you pick the right one before you write a line of code.

Three interaction models

CLI — the user types a command, the tool runs, produces output, and exits. The shell is back in control. Ideal for: automation, scripts, piping into other tools, batch operations. Examples: grep, jq, your-tool scan --output csv.

REPL (read-eval-print loop) — the tool prompts for input, evaluates it, prints a result, and loops. The session is stateful: results of earlier inputs affect later ones. Ideal for: exploratory data work, interactive debugging, language interpreters. Examples: python, psql, ipython.

TUI (text user interface) — the tool takes over the terminal, renders a persistent screen, and responds to keyboard and mouse events in a loop. The UI stays visible and updates as the state changes. The user navigates rather than types commands. Ideal for: dashboards, file managers, configuration editors, log viewers, interactive process monitors. Examples: htop, lazygit, ranger.

When a TUI is the right choice

Use a TUI when:

• The user needs to see multiple pieces of information simultaneously and the layout of that information matters.
• Navigation — moving between panels, scrolling a list, selecting items — is the primary interaction, not typing commands.
• The state updates continuously (a live log stream, CPU usage, a progress summary) and the user needs to see changes without rerunning the command.
• The interaction cannot be scripted or automated — it genuinely requires a human in the loop.

Avoid a TUI when the tool is used in scripts, when output needs to be piped, or when users will run it in non-interactive environments like CI pipelines.

Python TUI libraries

textual (recommended) — a modern, Pythonic TUI framework that uses CSS-like layout, reactive attributes, and an async event loop. First-class widget library including DataTable, Input, Button, Tree. Active maintenance and good documentation. This is the library this module uses.

urwid — the older, established option. Lower-level than textual; more flexible but requires more boilerplate. Well-tested and used in production (e.g. Wicd, some AWS tools).

curses — the standard library's binding to the POSIX curses interface. Works everywhere Python does, but the API is C-level: manually managing screen coordinates, attributes, and refresh calls. Use for maximum portability with minimal dependencies; use textual for everything else.

Where to go next

Next: textual basics — building a minimal Textual app with a Header, Footer, and Static widget, and wiring up a key binding to quit.