TUI Navigation

The Teabar TUI is designed for efficient keyboard navigation. Both vim-style keys and standard arrow keys are fully supported.

Navigation Philosophy

The TUI follows these principles:

Keyboard-first - Every action is accessible via keyboard
Vim + Arrows - Both navigation styles work equally
Consistent patterns - Same keys work similarly across views
Discoverable - Press ? for help at any time

Global Navigation

These shortcuts work in all views:

Key	Vim	Action
`Tab`	-	Next tab/pane
`Shift+Tab`	-	Previous tab/pane
`?`	-	Toggle help overlay
`q`	-	Quit TUI
`Ctrl+C`	-	Quit TUI
`/`	-	Focus search/filter
`Esc`	-	Close overlay / cancel / back
`R`	-	Refresh current view

Movement

Basic Movement

Arrow	Vim	Action
`↑`	`k`	Move up
`↓`	`j`	Move down
`←`	`h`	Collapse / move left / back
`→`	`l`	Expand / move right / enter

Extended Movement

Key	Action
`g`	Go to top of list
`G`	Go to bottom of list
`Ctrl+U`	Page up
`Ctrl+D`	Page down
`Home`	Go to top
`End`	Go to bottom

Tab Navigation

Switch between views using the tab bar:

┌─[ Environments ]─[ Logs ]─[ Catalog ]─[ Activity ]─────┐
     ^              ^         ^          ^
     1              2         3          4

Key	Action
`Tab`	Next tab
`Shift+Tab`	Previous tab
`1`	Environments view
`2`	Logs view
`3`	Catalog view
`4`	Activity view

Tip

Number keys (1-4) provide quick access to any view directly.

List Navigation

In list views (environments, blueprints, activity):

Key	Action
`↑/k`	Previous item
`↓/j`	Next item
`Enter`	Select / view details
`Space`	Toggle selection (multi-select)
`g`	First item
`G`	Last item

Multi-Select

Some views support selecting multiple items:

│   NAME             STATUS      BLUEPRINT         │
│ ✓ march-seminar    Running     gitlab-cicd       │  ← Selected
│   test-env         Sleeping    k8s-basics        │
│ ✓ demo             Running     argocd-demo       │  ← Selected

Key	Action
`Space`	Toggle current item selection
`a`	Select all
`n`	Select none
`*`	Invert selection

Then use action keys (like s for start, d for delete) to operate on all selected items.

Tree Navigation

In hierarchical views (environment details, component explorer):

│ Resources                      │
│ ├─ Cluster: main (3 nodes)     │  ← Collapsed
│ │   ├─ control-plane-1 ●       │
│ │   ├─ worker-1 ●              │
│ │   └─ worker-2 ●              │
│ ├─ VMs                         │  ← Collapsed
│ └─ Storage                     │  ← Collapsed

Key	Action
`→/l`	Expand node
`←/h`	Collapse node / go to parent
`Enter`	Toggle expand/collapse
`o`	Open node (expand)
`O`	Open all (expand recursively)
`c`	Close node (collapse)
`C`	Close all (collapse recursively)

Split Pane Navigation

In split-pane views (catalog browser, create wizard):

┌─ Left Pane ──────────────┐  ┌─ Right Pane ──────────────┐
│                          │  │                           │
│ Configuration            │  │ Preview                   │
│                          │  │                           │
└──────────────────────────┘  └───────────────────────────┘

Key	Action
`Tab`	Switch to other pane
`Shift+Tab`	Switch to other pane
`Ctrl+←`	Focus left pane
`Ctrl+→`	Focus right pane
`=`	Toggle 50/50 split
`Ctrl+\`	Maximize current pane

Form Navigation

In forms and wizards:

│ ▼ General                      │
│   Name: [march-seminar___]     │  ← Current field
│   TTL:  [48h ▼]                │
│                                │
│ ▼ Variables                    │
│   participant_count: [10_]     │

Key	Action
`↑/k`	Previous field
`↓/j`	Next field
`Enter`	Edit current field
`Space`	Toggle checkbox / open dropdown
`Tab`	Next field
`Shift+Tab`	Previous field
`Esc`	Cancel editing / close dropdown

Field Editing

When editing a field:

Key	Action
`Enter`	Confirm edit
`Esc`	Cancel edit
`Ctrl+A`	Select all
`Ctrl+U`	Clear field
`←/→`	Move cursor
`Backspace`	Delete character

Dropdowns

When a dropdown is open:

│   TTL:  [48h           ▼]     │
│         ┌───────────────┐     │
│         │ 1h            │     │
│         │ 4h            │     │
│         │ 8h            │     │
│         │▶24h           │  ← Selected
│         │ 48h           │
│         │ 7d            │
│         └───────────────┘     │

Key	Action
`↑/k`	Previous option
`↓/j`	Next option
`Enter`	Select option
`Esc`	Cancel selection
Type	Filter options

Dialog Navigation

In modal dialogs:

┌─ Confirm Delete ───────────────────────────────────────┐
│                                                        │
│ Delete environment 'march-seminar'?                    │
│                                                        │
│ This will permanently delete all resources.            │
│                                                        │
│             [ Cancel ]     [ Delete ]                  │
│                                                        │
└────────────────────────────────────────────────────────┘

Key	Action
`Tab`	Next button
`Shift+Tab`	Previous button
`Enter`	Activate focused button
`Esc`	Cancel / close dialog
`y`	Confirm (if confirmation dialog)
`n`	Cancel (if confirmation dialog)

Search and Filter

Press / to enter search mode:

│ Filter: kubectl_____________                           │
│ ▼ showing 23 of 156 results                            │

Key	Action
`/`	Start search
`Enter`	Apply filter
`Esc`	Clear filter
`Ctrl+U`	Clear input
`↑`	Previous search history
`↓`	Next search history

Search Syntax

Some views support advanced search:

# Simple text search
kubectl

# Field-specific search
type:kubectl

# Multiple terms (AND)
type:kubectl participant-3

# Status filter
status:failed

Log Viewer Navigation

Special navigation for the log viewer:

Key	Action
`f`	Toggle follow mode
`p`	Pause/resume
`↑/k`	Scroll up (when paused)
`↓/j`	Scroll down (when paused)
`g`	Go to oldest log
`G`	Go to newest log
`e`	Next error
`E`	Previous error
`n`	Next search match
`N`	Previous search match

Mouse Support

Mouse support is enabled by default:

Action	Effect
Click	Select item
Double-click	Open/activate item
Scroll	Scroll content
Click tab	Switch to view
Click button	Activate button

Disable mouse in config:

tui:
  mouse: false

Or via environment:

TEABAR_TUI_MOUSE=false teactl ui

Accessibility

Screen Reader Mode

For better screen reader compatibility:

teactl config set tui.accessibility.screen_reader true

High Contrast

Enable high contrast mode:

teactl config set tui.high_contrast true

No Color Mode

Disable all colors:

export NO_COLOR=1
teactl ui

Customization

Key Remapping

Key bindings can be customized in ~/.teactl/config.yaml:

tui:
  keybindings:
    quit: ["q", "ctrl+c"]
    help: ["?", "F1"]
    search: ["/", "ctrl+f"]

Note

Custom keybindings are merged with defaults. To remove a default binding, set it to an empty array.

Quick Reference Card

Print this for reference:

╔═══════════════════════════════════════════════════════╗
║              TEABAR TUI QUICK REFERENCE               ║
╠═══════════════════════════════════════════════════════╣
║ MOVEMENT        │ ACTIONS          │ VIEWS            ║
║ ↑/k    up       │ Enter  select    │ Tab    next tab  ║
║ ↓/j    down     │ Space  toggle    │ 1-4    goto tab  ║
║ ←/h    back     │ /      search    │                  ║
║ →/l    forward  │ ?      help      │                  ║
║ g      top      │ q      quit      │                  ║
║ G      bottom   │ R      refresh   │                  ║
╚═══════════════════════════════════════════════════════╝

TUI Overview - Introduction to the TUI
TUI Views - View-specific documentation
CLI Commands - Command-line interface