TUI Interactions Reference

What You Will Learn

• Navigate major views with predictable focus behavior.
• Use command and logs shortcuts without leaving the keyboard.
• Interpret hint bars and context-sensitive actions.
• Recover quickly when focus or state appears inconsistent.

Core Navigation Model

The TUI follows a consistent focus ring model across panels.

Use Tab and BackTab to move focus through interactive areas.

Use Enter to activate focused controls and Esc to dismiss overlays or modals.

Tab      -> Next focus target
Shift+Tab -> Previous focus target
Enter    -> Activate focused control
Esc      -> Close modal / return

expected Focus outline and hint text should always reflect the active interaction target.

recovery If focus appears lost, press Esc once or twice, then Tab to re-enter the expected focus cycle.

Global Shortcuts

Global shortcuts provide fast access to high-frequency panels.

These shortcuts are intended to reduce context switching during execution and debugging.

Ctrl+L -> Toggle logs panel
Ctrl+T -> Open theme picker
F1     -> Open command help (contextual)

tip Use logs and help shortcuts before rerunning failing commands to reduce trial-and-error loops.

Run Command Interaction Flow

Type search text in Run Command to open suggestions.

Use arrow keys to change selection and Enter to confirm.

Complete required inputs, run the command, and inspect results and logs.

# Typical loop
1) Type intent text
2) Tab / arrows through suggestions
3) Enter to select
4) Fill required args/flags
5) Execute and inspect output

expected Selected command details and execution output remain visible in the same workflow.

advanced Use Find/Browser for broader discovery, then hand selected commands back into Run Command.

Workflows and Input Collector

Workflow runs move through list selection, input collection, and execution monitoring.

Collector screens enforce required inputs before enabling run.

When provider-backed choices exist, select from list options before falling back to manual entry.

# Typical workflow loop
1) Select workflow
2) Open inputs
3) Provide required values
4) Run
5) Monitor step status and logs

expected Run actions become available only after required input validation passes.

recovery If run remains disabled, inspect collector errors and resolve missing required values first.

Mouse and Accessibility Behavior

Oatty supports mouse interactions for selection and button activation where available.

Keyboard access remains first-class and should always provide a complete interaction path.

Use large enough terminal dimensions to avoid clipped content and hidden controls.

tip If terminal rendering looks inconsistent, resize first, then reopen the current view before troubleshooting deeper issues.