bubbletea

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:

• Architecture & Core Methods: Learn the Elm Architecture, Model, Init, Update, and View.

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.

• The Charm Ecosystem: Using lipgloss for styling and bubbles for pre-built UI components.

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.