Overview

Date: 2026-05-11

Time: 15:52

Overview

This module provides a full-screen terminal UI (TUI) for ftl2-htop, a system monitoring dashboard built on FTL2's automation framework. It uses the Textual library to render a live-updating dashboard showing host metrics, and is designed to be compatible with textual-serve for web-based access. It's an alternative to the Rich live.Live rendering mode, activated via the --tui flag.

Usage Patterns

The primary entry point is run_tui(args), which accepts a parsed argument namespace and launches the Textual app:

from ftl2_htop.tui import run_tui
run_tui(args)  # args from argparse with hosts, inventory, interval, etc.

The app is typically launched from the CLI when the --tui flag is passed. It spawns a background thread that runs the FTL2 automation listener, while the main thread handles TUI rendering. Press q to quit.

API and Configuration

The args namespace controls behavior through these fields:

| Arg | Purpose |

|-----|---------|

| args.hosts | List of hostnames — builds an inline inventory |

| args.inventory | Path or dict for FTL2 inventory |

| args.state | State file path (alternative to inventory) |

| args.groups | Specific groups to monitor; defaults to all groups |

| args.interval | Polling interval for the monitor() call |

| args.no_processes | If true, skips per-process metrics |

Inventory resolution priority: hosts > inventory > state > fallback to "localhost,".

Key Behaviors

• Dual-thread architecture: The Textual event loop runs on the main thread; FTL2 automation runs in a daemon thread with its own asyncio event loop. Cross-thread updates use callfromthread.
• Refresh rates: Dashboard re-renders every 0.5s; status bar updates every 1.0s.
• Metrics flow: The worker subscribes to SystemMetrics events via proxy.on(). Each event updates metricsstore (a shared dict keyed by hostname) and records history via record_history.
• Error handling: Exceptions in the worker thread are caught and displayed in the status bar. The _finished flag is set regardless of success or failure.
• Empty inventory: If no groups are found after resolving inventory, the status bar shows a message and the worker exits without error.

Relationships

• Imports from ftl2htop: Uses metricsstore (shared dict) and renderdashboard() (Rich renderable generator) from the parent package. Also uses record_history for metric time-series tracking.
• Imports from ftl2: Uses ftl2.automation context manager as the core automation engine — sets up inventory, connects to hosts, and subscribes to metric events.
• Textual framework: Extends App, uses Header, Static, Binding. Compatible with textual-serve for browser-based rendering.
• Called by: The CLI entrypoint in ftl2_htop when --tui is passed.