Bubble Tea

The fun, functional and stateful way to build terminal apps. A Go framework based on The Elm Architecture. Bubble Tea is well-suited for simple and complex terminal applications, either inline, full-window, or a mix of both.

Bubble Tea is in use in production and includes a number of features and performance optimizations we’ve added along the way. Among those is a standard framerate-based renderer, a renderer for high-performance scrollable regions which works alongside the main renderer, and mouse support.

Getting Started

We recommend starting with the basics tutorial followed by the commands tutorial, both of which should give you a good understanding of how things work.

There are a bunch of examples, too!

Components

For a bunch of basic user interface components check out Bubbles, the official Bubble Tea component library.

  

Debugging

Debugging with Delve

Since Bubble Tea apps assume control of stdin and stdout, you’ll need to run delve in headless mode and then connect to it:

# Start the debugger
$ dlv debug --headless .
API server listening at: 127.0.0.1:34241

# Connect to it from another terminal
$ dlv connect 127.0.0.1:34241

Note that the default port used will vary on your system and per run, so actually watch out what address the first dlv run tells you to connect to.

Logging Stuff

You can log to a debug file to print debug Bubble Tea applications. To do so, include something like…

if len(os.Getenv("DEBUG")) > 0 {
	f, err := tea.LogToFile("debug.log", "debug")
	if err != nil {
		fmt.Println("fatal:", err)
		os.Exit(1)
	}
	defer f.Close()
}

…before you start your Bubble Tea program. To see what’s printed in real time, run tail -f debug.log while you run your program in another window.

Libraries we use with Bubble Tea

• Bubbles: Common Bubble Tea components such as text inputs, viewports, spinners and so on
• Lip Gloss: Style, format and layout tools for terminal applications
• Harmonica: A spring animation library for smooth, natural motion
• BubbleZone: Easy mouse event tracking for Bubble Tea components
• Termenv: Advanced ANSI styling for terminal applications
• Reflow: Advanced ANSI-aware methods for working with text

Bubble Tea in the Wild

For some Bubble Tea programs in production, see:

• AT CLI: a utility for executing AT Commands via serial port connections
• Aztify: bring Microsoft Azure resources under Terraform
• Canard: an RSS client
• charm: the official Charm user account manager
• circumflex: read Hacker News in your terminal
• clidle: a Wordle clone for your terminal
• container-canary: a container validator
• dns53: dynamic DNS with Amazon Route53. Expose your EC2 quickly, securely and privately
• fm: a terminal-based file manager
• flapioca: Flappy Bird on the CLI!
• fztea: connect to your Flipper's UI over serial or make it accessible via SSH
• fork-cleaner: cleans up old and inactive forks in your GitHub account
• gambit: play chess in the terminal
• gembro: a mouse-driven Gemini browser
• gh-b: GitHub CLI extension to easily manage your branches
• gh-dash: GitHub CLI extension to display a dashboard of PRs and issues
• gitflow-toolkit: a GitFlow submission tool
• Glow: a markdown reader, browser and online markdown stash
• gocovsh: explore Go coverage reports from the CLI
• httpit: a rapid http(s) benchmark tool
• IDNT: batch software uninstaller
• kboard: a typing game
• mandelbrot-cli: Multiplatform terminal mandelbrot set explorer
• mergestat: run SQL queries on git repositories
• mc: the official MinIO client
• pathos: pathos - CLI for editing a PATH env variable
• portal: securely send transfer between computers
• redis-viewer: browse Redis databases
• sku: a simple TUI for playing sudoku inside the terminal
• Slides: a markdown-based presentation tool
• Soft Serve: a command-line-first Git server that runs a TUI over SSH
• StormForge Optimize Controller: a tool for experimenting with application configurations in Kubernetes
• STTG: teletext client for SVT, Sweden’s national public television station
• sttr: run various text transformations
• tasktimer: a dead-simple task timer
• termdbms: a keyboard and mouse driven database browser
• ticker: a terminal stock watcher and stock position tracker
• tran: securely transfer stuff between computers (based on portal)
• tz: an aid for scheduling across multiple time zones
• ugm: a unix user and group browser
• Typer: a typing test
• wishlist: an SSH directory
• Noted: Note viewer and manager

Feedback

We'd love to hear your thoughts on this tutorial. Feel free to drop us a note!

• Twitter
• The Fediverse
• Slack

Acknowledgments

Bubble Tea is based on the paradigms of The Elm Architecture by Evan Czaplicki et alia and the excellent go-tea by TJ Holowaychuk. It’s inspired by the many great Zeichenorientierte Benutzerschnittstellen of days past.

License

MIT

---

Part of Charm.

Charm热爱开源 • Charm loves open source