Interactive Terminal UI (TUI)

The Hubfly space CLI includes a full-featured terminal user interface (TUI) built with Charm's Bubble Tea framework. It lets you manage projects, monitor live container metrics, open interactive shells, and toggle SSH tunnels without memorizing subcommands.

Bubble Tea TUI Overview

The TUI provides an event-driven terminal dashboard that streams state from the Hubfly space API. You can navigate through organizations, projects, containers, network ports, and persistent volumes directly inside your terminal window.

hubfly projects Command

Launch the interactive project dashboard:

terminal

$ hubfly projects

# Or filter by organization slug:

$ hubfly projects --org analytical-dev

Command / Flag	Type	Description
`hubfly projects`	Subcommand	Launches interactive TUI project workspace navigator.
`--org <id\|slug>`	Flag	Filter projects by organization ID or organization slug name.
`hubfly orgs`	Subcommand	Lists accessible organizations and displays organization details.

Keyboard Controls Reference

The TUI uses standard terminal keybindings for quick navigation:

Keybinding	Action
`↑ / ↓` or `j / k`	Move cursor selection up or down
`Enter`	Select project/container or confirm active selection
`Esc` / `Backspace`	Return to preceding menu level
`q` / `Ctrl+C`	Quit TUI application
`/` or direct typing	Filter items live by typing text search terms

Multi-Tunnel Management Screen

Inside the container detail view, you can open secure private network tunnels to one or multiple containers simultaneously:

Keybinding	Tunnel Action
`Space`	Toggle selection for current container tunnel target
`a`	Toggle selection for all containers in the project
`Enter`	Initialize and connect selected tunnel sessions

TUI Debug Logging

Because the TUI renders full-screen ANSI terminal buffers, standard debug logs cannot be printed directly to stdout. When running hubfly --debug projects, debug traces are redirected to:

~/.hubfly/logs/debug.log

To monitor debug logs in real time while using the TUI, tail the file in a separate terminal pane:

terminal

$ tail -f ~/.hubfly/logs/debug.log

[DEBUG] GET https://api.hubfly.space/v1/projects (status 200)

[DEBUG] Connecting WebSocket tunnel to gateway-1.hubfly.space...

Terminal Resize Support

The TUI automatically detects terminal window size adjustments and repaints container metrics, log viewports, and filterable tables dynamically.