tui

tui

A full-screen terminal UI framework for building interactive CLI applications — chat interfaces, log viewers, AI assistants, and more.

Layout

  Scrollable output / conversation history
  (auto-scrolls to bottom; Page Up/Down/wheel to scroll)

  Command palette (visible when / is typed)

┌─────────────────────────────────────── spinner / status ─┐
│                                                          │
│ > input goes here                                        │
│                                                          │
└─ myapp ──────────────────────────────────────────────────┘

The input box top border carries the spinner, progress bar, scroll hint, or StatusRight text (in that priority order). StatusLeft is embedded in the bottom border.

Multi-Panel Layout

The TUI supports multi-panel layouts using a two-step builder pattern: create panels, then add them to the layout.

┌─ logs ───┬─ main ──────────────────────┬─ stats ──┐
│          │                             │          │
│ [INFO]   │ Chat content here           │ CPU: 45% │
│ [WARN]   │                             │ MEM: 60% │
│          │                             │          │
└──────────┴─────────────────────────────┴──────────┘

Create panels and build the layout:

// Step 1: Create panels
logs := t.CreatePanel(tui.PanelConfig{
    Name:       "logs",
    Width:      -25,       // 25% of terminal width (negative = percentage)
    MinWidth:   15,        // Hide if narrower than 15 columns
    Scrollable: true,
    Title:      "Logs",
})
stats := t.CreatePanel(tui.PanelConfig{
    Name:       "stats",
    Width:      20,        // 20 columns (positive = fixed)
    MinWidth:   10,        // Hide if narrower than 10 columns
    Scrollable: false,     // Fixed content, overwrites on update
    Title:      "Stats",
    NoBorder:   false,     // Set true to hide border
})

// Step 2: Add panels to layout
t.AddLeft(logs)
t.AddRight(stats)

Panels can be nested with vertical splits using AddRow:

right := t.CreatePanel(tui.PanelConfig{Width: -30, MinWidth: 16})
statsCpu := t.CreatePanel(tui.PanelConfig{Name: "cpu", Height: -50, Title: "CPU"})
statsMem := t.CreatePanel(tui.PanelConfig{Name: "mem", Height: -50, Title: "Memory"})

right.AddRow(statsCpu)
right.AddRow(statsMem)

t.AddRight(right)

Clear and rebuild layouts at runtime:

// Remove all panels from layout (panels keep their content)
t.ClearLayout()

// Re-attach panels
t.AddLeft(logs)
t.AddRight(right)

Get a panel reference and write to it:

logs := t.Panel("logs")
logs.WriteString("[INFO] Server started\n")
logs.WriteString(logs.StyledWith("error", "[ERROR]") + " Connection failed\n")

stats := t.Panel("stats")
stats.SetContent("CPU: 45%\nMEM: 60%")  // Replaces all content

main := t.Panel("main")  // Main panel always exists
main.AddMessage(tui.RoleUser, "Hello!")

Panel features:

• All panels (including main) support AddMessage, StartStreaming, etc.
• WriteString for raw text with ANSI passthrough
• SetContent to replace content entirely (useful for fixed panels)
• WriteAt(row, col, text) for positioned writes
• ClearLine(row), ClearRegion(r1, c1, r2, c2) for partial clearing
• ScrollToTop, ScrollToBottom, ScrollUp(n), ScrollDown(n)
• Size() returns (width, height), ContentLines() returns line count
• SetTitle("") to remove title (unnamed panel)
• SetBorder(false) to hide border
• SetColor(color) for border accent
• Styled and StyledWith for themed colors

Navigation:

• Tab cycles focus through visible panels
• Focused panel has highlighted border
• Page Up/Down scrolls the focused panel
• Mouse wheel scrolls the panel under cursor

See tui/example-panels for a complete demo.

Quick Start

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/paularlott/cli/tui"
)

func main() {
    var t *tui.TUI

    t = tui.New(tui.Config{
        Theme:       tui.ThemeAmber,
        StatusLeft:  "myapp",
        StatusRight: "Ctrl+C to exit",
        Commands: []*tui.Command{
            {
                Name:        "exit",
                Description: "Exit the application",
                Handler:     func(_ string) { t.Exit() },
            },
            {
                Name:        "clear",
                Description: "Clear conversation history",
                Handler:     func(_ string) { t.ClearOutput() },
            },
        },
        OnSubmit: func(text string) {
            t.AddMessage(tui.RoleUser, text)
            t.AddMessage(tui.RoleAssistant, "Echo: "+text)
        },
    })

    t.AddMessage(tui.RoleSystem, "Welcome! Type / for commands.")

    if err := t.Run(context.Background()); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

Configuration

type Config struct {
    Theme          *Theme      // Active theme. Defaults to ThemeDefault.
    Themes         []*Theme    // Additional themes registered into the global registry.
    Commands       []*Command  // Slash commands shown in the palette.
    OnSubmit       func(text string)  // Called when the user submits input.
    OnEscape       func()             // Called when Escape is pressed outside the palette.
    OnFocusChange  func(panel *Panel) // Called when panel focus changes via Tab cycling.
    UserLabel      string      // Label for user messages. Empty string hides the header.
    AssistantLabel string      // Label for assistant messages. Empty string hides the header.
    SystemLabel    string      // Label for system messages. Empty string hides the header.
    StatusLeft     string      // Text shown bottom-left.
    StatusRight    string      // Text shown bottom-right (overridden by spinner/progress/scroll hint).
    ShowCharCount  bool        // Show character counter below the input box. Default: false.
    HideHeaders    bool        // Suppress all role headers regardless of label values. Default: false.
    InputEnabled   *bool       // Set to false for output-only / log-viewer mode.
}

Labels

Headers are shown only when a label is set. Empty string (the default) hides the header for that role.

// Set at construction time:
t = tui.New(tui.Config{
    UserLabel:      "You",
    AssistantLabel: "GPT-4o",
    SystemLabel:    "System",
})

// Update at runtime (empty string leaves that label unchanged):
t.SetLabels("You", "Claude 3.5", "")

Individual messages can override the default label:

t.AddMessageAs(tui.RoleAssistant, "GPT-4o", "Here is my answer…")
t.StartStreamingAs("Claude 3.5")

Messages

// Append a message from a standard role.
t.AddMessage(tui.RoleUser, "Hello!")
t.AddMessage(tui.RoleAssistant, "Hi there.")
t.AddMessage(tui.RoleSystem, "Connected.")

// Append a message with a custom label (overrides the role label for this message).
t.AddMessageAs(tui.RoleAssistant, "GPT-4o", "Here is my answer…")

// Clear all messages.
t.ClearOutput()

Message content supports fenced code blocks:

t.AddMessage(tui.RoleAssistant, "Example:\n\n```go\nfmt.Println(\"hello\")\n```")

Streaming

For token-by-token responses:

t.StartStreamingAs("Claude 3.5") // or t.StartStreaming() for the default label
for chunk := range tokenCh {
    if !t.IsStreaming() {
        break // stopped externally via StopStreaming()
    }
    t.StreamChunk(chunk)
}
t.StreamComplete()

// To stop early and finalise the message (e.g. from OnEscape):
t.StopStreaming()

Commands

All commands are supplied by the caller — there are no built-ins. Register them in Config.Commands at construction time, or add/remove them at runtime:

Commands: []*tui.Command{
    {
        Name:        "exit",
        Description: "Exit the application",
        Handler:     func(_ string) { t.Exit() },
    },
    {
        Name:        "theme",
        Description: "Switch theme",
        Args:        []string{"amber", "blue", "green"}, // shown as sub-options
        Handler: func(args string) {
            if th, ok := tui.ThemeByName(args); ok {
                t.SetTheme(th)
            }
        },
    },
},

// Add a command after construction:
t.AddCommand(&tui.Command{
    Name:        "save",
    Description: "Save current session",
    Handler:     func(_ string) { saveSession() },
})

// Remove a command by name:
t.RemoveCommand("save")

Type / to open the palette. Use ↑/↓ to navigate, Tab to complete, Enter to execute, Esc to close.

Spinner

Displays an animated braille spinner in the input box top border:

t.StartSpinner("Thinking…")
// … do work …
t.StopSpinner()

Calling StartSpinner while one is already running replaces the text. Starting a progress bar stops the spinner automatically.

Progress Bar

Displays a labelled progress bar in the input box top border:

for i := 0; i <= 100; i++ {
    t.SetProgress("Uploading…", float64(i)/100)
}
t.ClearProgress()

The border renders: ┌──────── Uploading… [████████████░░░░░░░░] 60% ┐

Spinner and progress bar are mutually exclusive. Both are overridden by the scroll hint when the user has scrolled up.

Status Bar

t.SetStatus("myapp", "v1.2.3")   // set both at once
t.SetStatusLeft("myapp")
t.SetStatusRight("v1.2.3")

Styled Text

Styled wraps a string in a theme color for use in message content:

t.AddMessage(tui.RoleSystem,
    tui.Styled(t.Theme().Text, "myapp") + "\n" +
    tui.Styled(t.Theme().Primary, "v1.2.3"),
)

t.Theme() returns the active theme so you can reference its color fields (Primary, Secondary, Text, Dim, Error, etc.) at call time, picking up any theme changes automatically.

Menus

t.OpenMenu(m) replaces the input box with a navigable bordered panel. t.CloseMenu() dismisses it programmatically.

t.OpenMenu(&tui.Menu{
    Title: "Settings",
    Items: []*tui.MenuItem{
        {
            Label: "Theme",
            Children: []*tui.MenuItem{          // sub-menu — shows › indicator
                {Label: "Amber", Value: "amber", OnSelect: func(item *tui.MenuItem, _ string) {
                    if th, ok := tui.ThemeByName(item.Value); ok { t.SetTheme(th) }
                }},
            },
        },
        {
            Label:  "API Key",
            Prompt: "Enter API key:",            // text-entry mode
            OnSelect: func(_ *tui.MenuItem, input string) {
                // input holds what the user typed
            },
        },
        {
            Label: "About",
            OnSelect: func(_ *tui.MenuItem, _ string) {
                t.AddMessage(tui.RoleSystem, "v1.0.0")
            },
        },
    },
})

MenuItem fields

Navigation

The title bar shows a breadcrumb when inside a sub-menu: Settings › Theme.

Output-Only Mode

Set InputEnabled to false to hide the input box, char count, and palette. Only scrolling and Ctrl+C remain active. Useful for log viewers or progress displays driven entirely by the application.

enabled := false
t = tui.New(tui.Config{
    InputEnabled: &enabled,
    // …
})

Context & Shutdown

Run accepts a context.Context. Cancelling the context shuts down the event loop cleanly:

ctx, cancel := context.WithCancel(context.Background())
// cancel() from anywhere to exit

t.Run(ctx)

// Retrieve the context later (e.g. inside a command handler):
ctx := t.Context()

t.Exit() is a convenience method that sets the quit flag directly — wire it to a /exit command.

Themes

Built-in themes

Selecting by name

if th, ok := tui.ThemeByName("amber"); ok {
    t.SetTheme(th)
}

// List all available theme names:
names := tui.ThemeNames() // ["amber", "blue", "default", "green", "light", "plain", "purple"]

Custom themes

Define a Theme struct and either pass it in Config.Themes (registered automatically) or call RegisterTheme directly:

myTheme := &tui.Theme{
    Name:      "solarized",
    Primary:   0x268BD2,
    Secondary: 0x2AA198,
    Text:      0x839496,
    UserText:  0x268BD2,
    Dim:       0x586E75,
    CodeBG:    0x073642,
    CodeText:  0x839496,
    Error:     0xDC322F,
}

// Option A — via Config (registered before Run):
t = tui.New(tui.Config{
    Themes: []*tui.Theme{myTheme},
    Theme:  myTheme,
})

// Option B — global registry at any time:
tui.RegisterTheme(myTheme)

Color values are 24-bit RGB packed as 0xRRGGBB. A zero value means the terminal's default color.

Keyboard Reference