The Problem: The UX Gap in Command-Line Tools
Standard Go tools like flag or Cobra are the workhorses of the ecosystem. They handle arguments perfectly, but they often leave users staring at a static wall of text. For simple tasks, this is fine. However, once your tool requires complex user input—like selecting resources or monitoring live data—the experience starts to feel dated and clunky.
I recently built a deployment tool for a team managing over 60 microservices across multiple clusters. Asking a DevOps engineer to copy-paste a 32-character deployment ID isn’t just slow; it is an invitation for a 2:00 AM production incident.
They needed an interface that felt alive. They wanted to scroll through lists, filter results instantly, and receive visual confirmation before hitting ‘deploy.’ Writing this from scratch with raw ANSI escape codes is a special kind of hell that involves manually tracking cursor coordinates and clearing lines. Most developers quit before they even finish the first menu.
The Root Cause: Why Terminal State is a Headache
Interactive CLIs are difficult because they don’t follow a linear path. A standard script runs from top to bottom: it reads input, executes logic, prints a result, and exits. A Terminal User Interface (TUI) functions more like a video game. It runs a continuous loop that must handle input and redraw the screen at least 60 times per second to feel smooth.
Managing this loop manually introduces three massive hurdles:
- Event Collisions: You have to handle keystrokes, window resizing, and background process completion simultaneously without locking the UI.
- Screen Flickering: If you clear the whole screen and redraw everything on every frame, the terminal will flicker violently. You need a way to only update the characters that actually changed.
- State Desync: It is easy for your internal data to get out of sync with what the user sees on the screen, especially when dealing with asynchronous API calls.
Evaluating the Options
When I looked for a better way to handle this in Go, I found three distinct paths:
1. Raw ANSI Codes
You can manually print strings like \033[2J to clear the screen or \033[H to move the cursor. This gives you total control but zero abstraction. It is like trying to build a modern web app by manually calculating pixel offsets for every letter. It doesn’t scale.
2. Imperative Libraries (Tview/Termbox)
These libraries provide widgets like buttons and forms. They work well for simple layouts, but they often rely on deeply nested callbacks. As your app grows to 1,000+ lines of code, tracking which callback updated which variable becomes an exercise in frustration.
3. Bubble Tea (The Elm Architecture)
Bubble Tea, built by the team at Charm, uses The Elm Architecture (TEA). Instead of telling the terminal how to change, you describe what the UI should look like for a given state. It is functional, predictable, and highly testable. After using it to build several internal tools, I’ve found it’s the only way to keep complex TUI code maintainable.
Implementing The Elm Architecture
Bubble Tea splits your application into three distinct parts: the Model (your data), the Update (your logic), and the View (your UI). This separation keeps your code clean even as features pile up.
Getting Started
Initialize your project and pull in the framework:
go mod init deploy-tool
go get github.com/charmbracelet/bubbletea1. The Model: Your Source of Truth
The Model is a simple struct. It holds every piece of data your UI needs. If you’re building a service picker, your model tracks the list, the current selection, and which items are checked.
type model struct {
services []string
cursor int
checked map[int]bool
}2. The Update Function: Handling Events
The Update function is the brain of your app. It takes an incoming message—like a keypress or an API response—and returns a new version of the model. This is where you handle navigation logic. Notice how clean the switch statement stays:
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyMsg:
switch msg.String() {
case "ctrl+c", "q":
return m, tea.Quit
case "up", "k":
if m.cursor > 0 { m.cursor-- }
case "down", "j":
if m.cursor < len(m.services)-1 { m.cursor++ }
case "enter", " ":
m.checked[m.cursor] = !m.checked[m.cursor]
}
}
return m, nil
}3. The View: Pure Formatting
The View function is a simple transformer. It reads the current state and returns a string. It doesn’t modify data; it just renders it. Because it is a pure function, you can trust that your UI always matches your data.
func (m model) View() string {
s := "Select services to deploy:\n\n"
for i, service := range m.services {
cursor := " "
if m.cursor == i { cursor = ">" }
checked := " "
if m.checked[i] { checked = "x" }
s += fmt.Sprintf("%s [%s] %s\n", cursor, checked, service)
}
return s + "\nPress q to quit.\n"
}Why This Matters for Production Tools
Predictability is the biggest win here. Since Update is just a function that takes a message and returns a state, you can write unit tests for your UI without ever opening a terminal. You can simulate 10 “down arrow” presses and assert that the cursor moved exactly 10 spaces. This level of confidence is impossible with traditional imperative TUI libraries.
This architecture also prevents “spaghetti code” as requirements change. When I needed to add a search bar to filter those 60 microservices, I didn’t have to touch the keyboard handling or the rendering logic. I just added a filter string to the Model, updated it in the Update function, and used it to slice the list in the View. The logic stayed isolated and easy to reason about.
Asynchronous Tasks and Side Effects
Real-world apps need to talk to APIs or databases. Bubble Tea handles this using tea.Cmd. A command is a background task that eventually sends a message back to your Update loop. This keeps your UI responsive. Your users can still navigate the menu while a 500ms network request is running in the background. No more frozen screens while waiting for a server response.
func (m model) Init() tea.Cmd {
return fetchServicesFromServer // Non-blocking background work
}The Bottom Line
Professional Go tools don’t have to be limited to boring, static text. By using Bubble Tea and The Elm Architecture, you can build interactive apps that are robust, testable, and actually pleasant to use. Internal tools are often the most used software in an organization. Giving them a polished, intuitive interface reduces errors and makes the development experience significantly better.
