Skip to content

tui.md

Latest commit

 

History

History
116 lines (90 loc) · 4.35 KB

tui.md

File metadata and controls

116 lines (90 loc) · 4.35 KB
Raw

Terminal Dashboard

gula tui opens an interactive terminal dashboard for an already running supervisor. It uses the same local Unix-domain-socket control plane as gula status, gula start, gula stop, and gula restart; it does not spawn a supervisor by itself.

# Terminal 1
gula run --config config/gula.yaml

# Terminal 2
gula tui

# Optional: tune the refresh cadence
gula tui --tick-ms 250

For a runnable local scenario that exercises log streaming, process control, readiness, restarts, and command hooks, see TUI Demo.

The command is built by the default tui Cargo feature. A lean CLI build can disable it with --no-default-features --features cli.

Supervisor Discovery

Discovery follows the same order as other operator commands:

  1. Hidden/advanced socket overrides (--socket <PATH> or $GULA_CONTROL_SOCKET)
  2. Runtime endpoint ($GULA_RUNTIME_DIR/control.sock, /run/gula, $XDG_RUNTIME_DIR/gula, or /tmp/gula-$UID)
  3. Legacy <config.logs_dir>/gula.sock from --config
  4. Legacy ./logs/gula.sock

For modern supervisors, --config is only a legacy socket fallback. --sys-config is rejected because the dashboard connects to an existing supervisor instead of starting one.

Views

The dashboard currently shows:

  • The supervisor PID, process count, socket path, refresh age, pause state, and log-follow mode.
  • A process table with name, lifecycle state, process group id, automatic retry count, CPU percentage, and resident memory.
  • Details for the selected process, including core, last exit code, and latest metrics timestamp.
  • Recent stdout/stderr lines for the selected process.
  • Pending process-control operations and the latest status/error message.

The TUI reads point-in-time snapshots on a timer. CPU, memory, and core fields therefore represent the most recent monitor sample, not a streaming metrics subscription.

Keys

Key Action
j / Down Select next process
k / Up Select previous process
u Refresh immediately
Space Pause/resume automatic refresh
f Toggle log follow mode
PageUp / PageDown Scroll the selected process's log pane up or down
Home / End Jump the selected process's log pane to oldest buffered line or resume following the newest line
a Start the selected process
s Stop the selected process
r Restart the selected process
S Stop all currently stoppable processes
R Restart all currently restartable processes
y / Enter Confirm a pending start/stop/restart
n / Esc Cancel a pending start/stop/restart
q / Esc / Ctrl-C Quit

Start, stop, and restart use the same state validation and operation polling as the corresponding CLI commands. A request may be rejected immediately if the selected process is in a state where that action is not valid. Restarting from the dashboard is a per-process operator action; it does not replay dependency graphs and does not increment the automatic retry counter.

The all-process S and R shortcuts are batches of those same per-process requests. They target only rows whose current state already allows stop or restart; they do not restart terminal setup jobs or replay dependency waits.

Logs

Log panes are backed by log_config.ring_buffer_size, not by tailing log files from disk. If a process has no ring buffer configured, the dashboard still shows process state and metrics, but the log pane is empty.

processes:
  - name: worker
    command: ./worker
    log_config:
      ring_buffer_size: 500

Each log line carries a per-process sequence number and stream label (stdout or stderr). The dashboard asks for lines after the last sequence number it saw and clears its local view if the supervisor reports truncation or the process's in-memory log sequence resets after a restart.

Follow mode keeps the log pane pinned to the newest buffered line. PageUp, PageDown, and Home leave follow mode so the current view stays stable while new log lines arrive; End or toggling follow back on returns to the newest line.

The server caps each log response so accidental large refreshes stay bounded. Large historical logs remain available in <logs_dir>/<process>.log when file logging is enabled.

Exit Codes

  • 0 — dashboard exited normally
  • 1 — startup or terminal setup failed
  • 2 — no running supervisor could be found