| name | bubbletea |
| description | The complete guide for an AI agent to build Terminal UIs (TUIs) in Go using Bubble Tea (Elm architecture, Model-Update-View, Lipgloss, Bubbles). Use when creating or modifying CLI tools that need an interactive interface. |
Bubble Tea Developer Guide
Bubble Tea is a powerful Go framework for building terminal user interfaces (TUIs). Because TUIs are highly interactive and run directly in the terminal, they have specific architectural requirements and constraints that differ from standard CLI scripts.
Core Concepts
If you are new to Bubble Tea or need a refresher on the fundamental structure, start here:
Managing State & I/O
Bubble Tea requires all state changes to happen in the Update loop. Blocking operations will freeze the UI.
- Commands & Messages: How to handle async operations, timers, and external events using
tea.Cmd and tea.Msg.
Styling and Components
Do not build complex components (text inputs, lists, spinners) or styling (colors, layout) from scratch.
Troubleshooting
Because Bubble Tea owns the standard output, traditional debugging techniques like fmt.Println will break the terminal display.
- Debugging & Gotchas: Essential rules for debugging Bubble Tea apps, logging to files, headless debugging, and V1 vs V2 differences.
