TUI Components Overview

Invowk™ includes a set of interactive terminal UI components inspired by gum. Use them in your scripts to create interactive prompts, selections, and styled output.

Available Components

Component	Description	Use Case
input	Single-line text input	Names, paths, simple values
write	Multi-line text editor	Descriptions, commit messages
choose	Select from options	Menus, choices
confirm	Yes/no prompt	Confirmations
filter	Fuzzy filter list	Search through options
file	File picker	Select files/directories
table	Display tabular data	CSV, data tables
spin	Spinner with command	Long-running tasks
pager	Scrollable content viewer	Logs, code review, long output
format	Format text (markdown, code)	Rendering content
style	Style text (colors, bold)	Decorating output

Quick Examples

# Get user input
NAME=$(invowk tui input --title "What's your name?")

# Choose from options
COLOR=$(invowk tui choose --title "Pick a color" red green blue)

# Confirm action
if invowk tui confirm "Continue?"; then
    echo "Proceeding..."
fi

# Show spinner during long task
invowk tui spin --title "Installing..." -- npm install

# Style output
echo "Success!" | invowk tui style --foreground "#00FF00" --bold

Using in Invkfiles

TUI components work great inside command scripts, including those running in containers with interactive mode (-i):

Container Support

TUI components work seamlessly inside containers when using interactive mode. The components render as modal overlays on your host terminal. See Container Runtime - Interactive Mode for details.

{
    name: "setup"
    description: "Interactive project setup"
    implementations: [{
        script: """
            #!/bin/bash
            
            # Gather information
            NAME=$(invowk tui input --title "Project name:")
            TYPE=$(invowk tui choose --title "Type:" cli library api)
            
            # Confirm
            echo "Creating $TYPE project: $NAME"
            if ! invowk tui confirm "Proceed?"; then
                echo "Cancelled."
                exit 0
            fi
            
            # Execute with spinner
            invowk tui spin --title "Creating project..." -- mkdir -p "$NAME"
            
            # Success message
            echo "Project created!" | invowk tui style --foreground "#00FF00" --bold
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Common Patterns

Input with Validation

while true; do
    EMAIL=$(invowk tui input --title "Email address:")
    if echo "$EMAIL" | grep -qE '^[^@]+@[^@]+\.[^@]+$'; then
        break
    fi
    echo "Invalid email format" | invowk tui style --foreground "#FF0000"
done

Menu System

ACTION=$(invowk tui choose --title "What would you like to do?" \
    "Build project" \
    "Run tests" \
    "Deploy" \
    "Exit")

case "$ACTION" in
    "Build project") make build ;;
    "Run tests") make test ;;
    "Deploy") make deploy ;;
    "Exit") exit 0 ;;
esac

Progress Feedback

echo "Step 1: Installing dependencies..."
invowk tui spin --title "Installing..." -- npm install

echo "Step 2: Building..."
invowk tui spin --title "Building..." -- npm run build

echo "Done!" | invowk tui style --foreground "#00FF00" --bold

Styled Headers

invowk tui style --bold --foreground "#00BFFF" "=== Project Setup ==="
echo ""
# ... rest of script

Piping and Capture

Most components work with pipes:

# Pipe to filter
ls | invowk tui filter --title "Select file"

# Capture output
SELECTED=$(invowk tui choose opt1 opt2 opt3)
echo "You selected: $SELECTED"

# Pipe for styling
echo "Important message" | invowk tui style --bold

Exit Codes

Components use exit codes to communicate:

Component	Exit 0	Exit 1
confirm	User said yes	User said no
input	Value entered	Cancelled
choose	Option selected	Cancelled
filter	Option selected	Cancelled
pager	Exited normally	Error occurred

Use in conditionals:

if invowk tui confirm "Delete files?"; then
    rm -rf ./temp
fi

Next Steps

Explore each component in detail:

• Input and Write - Text entry
• Choose and Confirm - Selection and confirmation
• Filter and File - Search and file picking
• Table and Spin - Data display and spinners
• Pager - Scrollable content viewing
• Format and Style - Text formatting and styling