Zorvia Interactive TUI Guide

Canonical interactive TUI documentation (other TUI markdown files in this folder are short pointers here).

Overview

Zorvia provides a fully interactive Terminal User Interface (TUI) with dialogs, forms, context menus, and real-time notifications for managing KubeVirt VMs.

Launching the TUI

Basic Mode

# Launch basic TUI
zorvia tui

# With specific namespace
zorvia tui --namespace production

Enhanced Interactive Mode

# Launch with full interactive features
zorvia tui --interactive

# With custom theme
zorvia tui --interactive --theme dark

Interactive Features

🎯 Dialogs & Confirmations

The interactive TUI shows confirmation dialogs for destructive operations:

Start VM: Press s on a stopped VM → Confirmation dialog
Stop VM: Press x on a running VM → Confirmation dialog
Delete VM: Press d on any VM → Warning confirmation dialog

Dialog Controls:

← / → / Tab: Toggle between Yes/No
Enter: Confirm selection
Esc: Cancel

📝 Input Forms

Create resources with interactive forms:

Create VM (Press c in VM List):

┌────── Create Virtual Machine ──────┐
│ VM Name:                           │
│   my-vm█                           │
│                                    │
│ Template:                          │
│   ubuntu-22.04                     │
│                                    │
│ Profile:                           │
│   dev                              │
│                                    │
│ Disk Size:                         │
│   20Gi                             │
│                                    │
│  [ Submit ]  [ Cancel ]            │
│                                    │
│ Tab: Next field | Enter: Submit    │
└────────────────────────────────────┘

Form Controls:

Tab: Move to next field
Shift+Tab: Move to previous field
Type to edit current field
Backspace: Delete character
Enter: Submit form
Esc: Cancel

Create Snapshot (Press c in Snapshots):

Auto-fills current VM name
Prompts for snapshot name
Creates snapshot on submit

📋 Context Menus

Right-click style menus with keyboard navigation (Press m in VM List):

┌────── VM: my-ubuntu ──────┐
│ ▶ Start (s)               │
│   Delete (d)              │
│   Create Snapshot (c)     │
│   View Details (v)        │
│   Edit (e) [disabled]     │
└───────────────────────────┘

Menu Controls:

↑ / ↓ / j / k: Navigate items
Enter: Select highlighted item
Type the key letter (e.g., s for Start)
Esc: Close menu

Dynamic Menus:

Running VMs show: Stop, Restart, Create Snapshot
Stopped VMs show: Start, Delete
Disabled items shown in gray

🔔 Toast Notifications

Non-intrusive notifications appear in the top-right corner:

Types:

Info (Blue ℹ): "Refreshing data..."
Success (Green ✓): "VM 'my-vm' started successfully"
Warning (Yellow ⚠): "VM may take a few minutes to start"
Error (Red ✗): "Failed to connect to cluster"

Features:

Auto-dismiss after 3 seconds
Stack multiple notifications
Don't block user interaction

🔍 Search & Filter

Press / to activate search bar:

┌────────────────────────────┐
│ Search: ubuntu█            │
└────────────────────────────┘

Search Controls:

/: Open search bar
Type to filter
Enter or Esc: Close search
Filters VM list in real-time

⏳ Progress Indicators

Long-running operations show progress:

┌─────── Creating VM ───────┐
│                           │
│  Creating VM 'web-01'...  │
│                           │
│  ████████░░░░░░░░░  45%   │
│                           │
└───────────────────────────┘

Types:

Determinate: Shows percentage (VM creation, snapshot)
Indeterminate: Spinner for unknown duration (waiting for status)

Global Keybindings

Key	Action
`1`	Dashboard
`2`	VM List
`3`	Snapshots
`4`	Profiles
`5`	Blueprints
`?`	Help Screen
`Ctrl+R`	Refresh Data
`/`	Search/Filter
`q` or `Esc`	Quit

VM List View

Key	Action
`↑↓` or `j/k`	Navigate VMs
`Enter`	View details
`m`	Open context menu
`c`	Create new VM
`s`	Start selected VM
`x`	Stop selected VM
`d`	Delete selected VM

Snapshots View

Key	Action
`↑↓` or `j/k`	Navigate snapshots
`c`	Create snapshot
`d`	Delete snapshot
`r`	Restore snapshot

VM Details View

Key	Action
`Backspace` or `Esc`	Return to VM list

Interactive Workflows

Creating a VM

Press 2 → Navigate to VM List
Press c → Open "Create VM" form
Fill in fields:
- VM Name: web-server
- Template: ubuntu-22.04
- Profile: web
- Disk Size: 40Gi
Press Enter → Submit
Toast notification: "Creating VM 'web-server'..."
Progress indicator shows creation status
Success notification: "VM 'web-server' created"
Auto-refresh shows new VM in list

Managing a VM

Navigate to VM in list (↑↓)
Press m → Open context menu
Select action:
- s → Start VM (with confirmation)
- x → Stop VM (with confirmation)
- c → Create snapshot
- v → View details
Confirm action in dialog
Real-time notification of status
VM list auto-updates

Taking a Snapshot

Navigate to Snapshots view (3)
Press c → Open "Create Snapshot" form
VM name auto-filled
Enter snapshot name: backup-2026-02-11
Press Enter → Submit
Progress bar shows snapshot creation
Success notification
Snapshot appears in list

Customization

Themes

# Dark theme (default)
zorvia tui --interactive --theme dark

# Light theme
zorvia tui --interactive --theme light

Configuration

Edit ~/.config/zorvia/tui.toml:

[theme]
name = "dark"

[ui]
auto_refresh_interval = 5
show_timestamps = true

[behavior]
confirm_stop = true
confirm_delete = true

Advanced Features

Multi-Select Operations (Coming Soon)

Select multiple VMs with Space
Batch operations with confirmation
Progress for multiple VMs

Custom Keybindings (Configurable)

[keybindings]
quit = "q"
refresh = "r"
search = "/"
create = "c"

Mouse Support (Optional)

Click to select items
Click buttons in dialogs
Scroll with mouse wheel

Tips & Tricks

Quick Actions: Use single-key shortcuts (s, x, d) instead of menu for speed
Search Everything: Press / to filter large VM lists quickly
Keyboard Only: Entire TUI navigable without mouse
Confirmation Dialogs: Default selection is "No" for safety
Auto-Refresh: Data refreshes every 5 seconds automatically
Stack Notifications: Multiple actions show stacked notifications
Escape Hatch: Esc always closes dialogs/menus/search

Troubleshooting

Dialog not appearing?

Ensure terminal is large enough (minimum 80x24)
Try maximizing terminal window

Notifications disappearing too fast?

Edit config: notification_duration = 5 (seconds)

Colors look wrong?

Check terminal supports 256 colors
Try different theme: --theme light

Keyboard shortcuts not working?

Check if terminal emulator intercepts keys
Some keys may conflict with terminal shortcuts

Comparison: Basic vs Interactive Mode

Feature	Basic Mode	Interactive Mode
View navigation	✓	✓
List navigation	✓	✓
Confirmation dialogs	✗	✓
Input forms	✗	✓
Context menus	✗	✓
Toast notifications	✗	✓
Progress indicators	✗	✓
Search/filter	✗	✓
Real-time updates	✓	✓

Examples

Complete Workflow: Deploy a Web Application

# Launch interactive TUI
zorvia tui --interactive

# Create database VM
1. Press 2 (VM List)
2. Press c (Create)
3. Fill: name=db, template=postgres, profile=database
4. Submit

# Create web server VMs
5. Press c (Create)
6. Fill: name=web-01, template=ubuntu-22.04, profile=web
7. Submit
8. Repeat for web-02, web-03

# Verify all running
9. See all VMs in list with green "Running" status

# Take snapshots before deployment
10. Press 3 (Snapshots)
11. For each VM, press c, name snapshot "pre-deploy"
12. Notifications confirm snapshots created

# Monitor in dashboard
13. Press 1 (Dashboard)
14. View: 4 Running, 0 Stopped

Keyboard Shortcuts Reference Card

┌─────────────────────────────────────────┐
│         Zorvia TUI Shortcuts         │
├─────────────────────────────────────────┤
│ NAVIGATION                              │
│  1-5        Switch views                │
│  ↑↓ / jk    Navigate lists              │
│  Enter      Select / Details            │
│  Backspace  Go back                     │
│                                         │
│ ACTIONS                                 │
│  c          Create new                  │
│  s          Start / Stop                │
│  d          Delete                      │
│  m          Context menu                │
│                                         │
│ GLOBAL                                  │
│  /          Search                      │
│  Ctrl+R     Refresh                     │
│  ?          Help                        │
│  q / Esc    Quit / Cancel               │
└─────────────────────────────────────────┘

Save this card for quick reference!

Overview​

Launching the TUI​

Basic Mode​

Enhanced Interactive Mode​

Interactive Features​

🎯 Dialogs & Confirmations​

📝 Input Forms​

📋 Context Menus​

🔔 Toast Notifications​

🔍 Search & Filter​

⏳ Progress Indicators​

View Navigation​

Global Keybindings​

VM List View​

Snapshots View​

VM Details View​

Interactive Workflows​

Creating a VM​

Managing a VM​

Taking a Snapshot​

Customization​

Themes​

Configuration​

Advanced Features​

Multi-Select Operations (Coming Soon)​

Custom Keybindings (Configurable)​

Mouse Support (Optional)​

Tips & Tricks​

Troubleshooting​

Comparison: Basic vs Interactive Mode​

Examples​

Complete Workflow: Deploy a Web Application​

Keyboard Shortcuts Reference Card​