• Stars
    star
    26,561
  • Rank 757 (Top 0.02 %)
  • Language
    Go
  • License
    MIT License
  • Created almost 5 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A powerful little TUI framework πŸ—

Bubble Tea

Bubble Tea Title Treatment
Latest Release GoDoc Build Status phorm.ai

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 Example

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.

To get started, see the tutorial below, the examples, the docs, the video tutorials and some common resources.

By the way

Be sure to check out Bubbles, a library of common UI components for Bubble Tea.

Bubbles BadgeΒ Β  Text Input Example from Bubbles


Tutorial

Bubble Tea is based on the functional design paradigms of The Elm Architecture, which happens to work nicely with Go. It's a delightful way to build applications.

This tutorial assumes you have a working knowledge of Go.

By the way, the non-annotated source code for this program is available on GitHub.

Enough! Let's get to it.

For this tutorial, we're making a shopping list.

To start we'll define our package and import some libraries. Our only external import will be the Bubble Tea library, which we'll call tea for short.

package main

import (
    "fmt"
    "os"

    tea "github.com/charmbracelet/bubbletea"
)

Bubble Tea programs are comprised of a model that describes the application state and three simple methods on that model:

  • Init, a function that returns an initial command for the application to run.
  • Update, a function that handles incoming events and updates the model accordingly.
  • View, a function that renders the UI based on the data in the model.

The Model

So let's start by defining our model which will store our application's state. It can be any type, but a struct usually makes the most sense.

type model struct {
    choices  []string           // items on the to-do list
    cursor   int                // which to-do list item our cursor is pointing at
    selected map[int]struct{}   // which to-do items are selected
}

Initialization

Next, we’ll define our application’s initial state. In this case, we’re defining a function to return our initial model, however, we could just as easily define the initial model as a variable elsewhere, too.

func initialModel() model {
	return model{
		// Our to-do list is a grocery list
		choices:  []string{"Buy carrots", "Buy celery", "Buy kohlrabi"},

		// A map which indicates which choices are selected. We're using
		// the  map like a mathematical set. The keys refer to the indexes
		// of the `choices` slice, above.
		selected: make(map[int]struct{}),
	}
}

Next, we define the Init method. Init can return a Cmd that could perform some initial I/O. For now, we don't need to do any I/O, so for the command, we'll just return nil, which translates to "no command."

func (m model) Init() tea.Cmd {
    // Just return `nil`, which means "no I/O right now, please."
    return nil
}

The Update Method

Next up is the update method. The update function is called when ”things happen.” Its job is to look at what has happened and return an updated model in response. It can also return a Cmd to make more things happen, but for now don't worry about that part.

In our case, when a user presses the down arrow, Update’s job is to notice that the down arrow was pressed and move the cursor accordingly (or not).

The β€œsomething happened” comes in the form of a Msg, which can be any type. Messages are the result of some I/O that took place, such as a keypress, timer tick, or a response from a server.

We usually figure out which type of Msg we received with a type switch, but you could also use a type assertion.

For now, we'll just deal with tea.KeyMsg messages, which are automatically sent to the update function when keys are pressed.

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {

    // Is it a key press?
    case tea.KeyMsg:

        // Cool, what was the actual key pressed?
        switch msg.String() {

        // These keys should exit the program.
        case "ctrl+c", "q":
            return m, tea.Quit

        // The "up" and "k" keys move the cursor up
        case "up", "k":
            if m.cursor > 0 {
                m.cursor--
            }

        // The "down" and "j" keys move the cursor down
        case "down", "j":
            if m.cursor < len(m.choices)-1 {
                m.cursor++
            }

        // The "enter" key and the spacebar (a literal space) toggle
        // the selected state for the item that the cursor is pointing at.
        case "enter", " ":
            _, ok := m.selected[m.cursor]
            if ok {
                delete(m.selected, m.cursor)
            } else {
                m.selected[m.cursor] = struct{}{}
            }
        }
    }

    // Return the updated model to the Bubble Tea runtime for processing.
    // Note that we're not returning a command.
    return m, nil
}

You may have noticed that ctrl+c and q above return a tea.Quit command with the model. That’s a special command which instructs the Bubble Tea runtime to quit, exiting the program.

The View Method

At last, it’s time to render our UI. Of all the methods, the view is the simplest. We look at the model in its current state and use it to return a string. That string is our UI!

Because the view describes the entire UI of your application, you don’t have to worry about redrawing logic and stuff like that. Bubble Tea takes care of it for you.

func (m model) View() string {
    // The header
    s := "What should we buy at the market?\n\n"

    // Iterate over our choices
    for i, choice := range m.choices {

        // Is the cursor pointing at this choice?
        cursor := " " // no cursor
        if m.cursor == i {
            cursor = ">" // cursor!
        }

        // Is this choice selected?
        checked := " " // not selected
        if _, ok := m.selected[i]; ok {
            checked = "x" // selected!
        }

        // Render the row
        s += fmt.Sprintf("%s [%s] %s\n", cursor, checked, choice)
    }

    // The footer
    s += "\nPress q to quit.\n"

    // Send the UI for rendering
    return s
}

All Together Now

The last step is to simply run our program. We pass our initial model to tea.NewProgram and let it rip:

func main() {
    p := tea.NewProgram(initialModel())
    if _, err := p.Run(); err != nil {
        fmt.Printf("Alas, there's been an error: %v", err)
        os.Exit(1)
    }
}

What’s Next?

This tutorial covers the basics of building an interactive terminal UI, but in the real world you'll also need to perform I/O. To learn about that have a look at the Command Tutorial. It's pretty simple.

There are also several Bubble Tea examples available and, of course, there are Go Docs.

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-version=2 --listen=127.0.0.1:43000 .
API server listening at: 127.0.0.1:43000

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

If you do not explicitly supply the --listen flag, the port used will vary per run, so passing this in makes the debugger easier to use from a script or your IDE of choice.

Additionally, we pass in --api-version=2 because delve defaults to version 1 for backwards compatibility reasons. However, delve recommends using version 2 for all new development and some clients may no longer work with version 1. For more information, see the Delve documentation.

Logging Stuff

You can’t really log to stdout with Bubble Tea because your TUI is busy occupying that! You can, however, log to a file by including something like the following prior to starting your Bubble Tea program:

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()
}

To see what’s being logged 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:

  • ASCII Movie: a Star Wars ASCII art movie player
  • AT CLI: execute AT Commands via serial port connections
  • Aztify: bring Microsoft Azure resources under Terraform
  • brows: a GitHub release browser
  • Canard: an RSS client
  • charm: the official Charm user account manager
  • chatgpt-cli: a CLI for ChatGPT
  • chatgpt-tui: a TUI for ChatGPT with SQLite sessions
  • ChatGPTUI: a TUI for ChatGPT
  • chezmoi: securely manage your dotfiles across multiple machines
  • chip-8: a CHIP-8 interpreter
  • chtop: monitor your ClickHouse node without leaving the terminal
  • circumflex: read Hacker News in the terminal
  • clidle: a Wordle clone
  • cLive: automate terminal operations and view them live in a browser
  • container-canary: a container validator
  • countdown: a multi-event countdown timer
  • CRT: a simple terminal emulator for running Bubble Tea in a dedicated window, with optional shaders
  • cueitup: inspect messages in an AWS SQS queue in a simple and deliberate manner
  • Daytona: an development environment manager
  • dns53: dynamic DNS with Amazon Route53; expose your EC2 quickly, securely and privately
  • eks-node-viewer: a tool for visualizing dynamic node usage within an EKS cluster
  • End Of Eden: a "Slay the Spire"-like, roguelike deck-builder game
  • enola: find social media accounts by username across social networks
  • flapioca: Flappy Bird on the CLI!
  • fm: a terminal-based file manager
  • fork-cleaner: clean up old and inactive forks in your GitHub account
  • fractals-cli: a multiplatform terminal fractal explorer
  • fztea: a Flipper Zero TUI
  • gama: manage GitHub Actions from the terminal
  • gambit: chess in the terminal
  • gembro: a mouse-driven Gemini browser
  • gh-b: a GitHub CLI extension for managing branches
  • gh-dash: a GitHub CLI extension for PRs and issues
  • gitflow-toolkit: a GitFlow submission tool
  • Glow: a markdown reader, browser, and online markdown stash
  • go-sweep: Minesweeper in the terminal
  • gocovsh: explore Go coverage reports from the CLI
  • got: a simple translator and text-to-speech app built on simplytranslate's APIs
  • gum: interactivity and styling for shells and shell scripts
  • hiSHtory: your shell history in context: synced, and queryable
  • httpit: a rapid http(s) benchmark tool
  • Huh?: an interactive prompt and form toolkit
  • IDNT: a batch software uninstaller
  • json-log-viewer: an interactive JSON log viewer
  • kboard: a typing game
  • kplay: inspect messages in a Kafka topic
  • laboon: a Docker-desktop-style container manager
  • mc: the official MinIO client
  • mergestat: run SQL queries on git repositories
  • meteor: a highly customizable conventional commit message tool
  • mods: AI on the CLI, built for pipelines
  • nachrichten: access up-to-date news in German provided by the Tagesschau
  • Neon Modem Overdrive: a BBS-style TUI client for Discourse, Lemmy, Lobste.rs and Hacker News
  • nom: an RSS reader and manager
  • Noted: a note viewer and manager
  • outtasync: identify CloudFormation stacks that are out of sync with their template files
  • pathos: a PATH environment variable editor
  • Plandex: a terminal-based AI coding engine for complex tasks
  • portal: secure transfers between computers
  • prs: stay up to date with your PRs
  • puffin: a TUI for hledger to manage your finances
  • punchout: takes the suck out of logging time on JIRA
  • redis-viewer: a Redis database browser
  • redis_tui: a Redis database browser
  • schemas: lets you inspect postgres schemas in the terminal
  • scrabbler: an automatic draw tool for your duplicate Scrabble games
  • sku: Sudoku on the CLI
  • Slides: a markdown-based presentation tool
  • SlurmCommander: a Slurm workload manager
  • Soft Serve: a command-line-first Git server that runs a TUI over SSH
  • solitaire-tui: Klondike Solitaire for the terminal
  • StormForge Optimize Controller: a tool for experimenting with application configurations in Kubernetes
  • Storydb: an improved bash/zsh-style ctrl+r command history finder
  • STTG: a teletext client for SVT, Sweden’s national public television station
  • sttr: a general-purpose text transformer
  • tasktimer: a dead-simple task timer
  • termdbms: a keyboard and mouse driven database browser
  • tgpt: conversational AI for the CLI; no API keys necessary
  • ticker: a terminal stock viewer and stock position tracker
  • trainer: a Go concurrency coding interview simulator with learning materials
  • tran: securely transfer stuff between computers (based on portal)
  • Trufflehog: find leaked credentials
  • Typer: a typing test
  • typioca: a typing test
  • tz: a scheduling aid for people in multiple time zones
  • ugm: a unix user and group browser
  • walk: a terminal navigator
  • wander: a HashiCorp Nomad terminal client
  • WG Commander: a TUI for a simple WireGuard VPN setup
  • wishlist: an SSH directory

Feedback

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

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.

The Charm logo

Charmηƒ­ηˆ±εΌ€ζΊ β€’ Charm loves open source β€’ نحنُ Ω†Ψ­Ψ¨ Ψ§Ω„Ω…Ψ΅Ψ§Ψ―Ψ± المفΨͺوحة

More Repositories

1

gum

A tool for glamorous shell scripts πŸŽ€
Go
17,705
star
2

glow

Render markdown on the CLI, with pizzazz! πŸ’…πŸ»
Go
15,692
star
3

vhs

Your CLI home video recorder πŸ“Ό
Go
14,678
star
4

lipgloss

Style definitions for nice terminal layouts πŸ‘„
Go
7,832
star
5

bubbles

TUI components for Bubble Tea 🫧
Go
5,325
star
6

soft-serve

The mighty, self-hostable Git server for the command line🍦
Go
5,174
star
7

huh

Build terminal forms and prompts πŸ€·πŸ»β€β™€οΈ
Go
3,994
star
8

wish

Make SSH apps, just like that! πŸ’«
Go
3,428
star
9

freeze

Generate images of code and terminal output πŸ“Έ
Go
3,091
star
10

mods

AI on the command line
Go
2,830
star
11

pop

Send emails from your terminal πŸ“¬
Go
2,382
star
12

glamour

Stylesheet-based markdown rendering for your CLI apps πŸ’‡πŸ»β€β™€οΈ
Go
2,369
star
13

charm

The Charm Tool and Library 🌟
Go
2,351
star
14

log

A minimal, colorful Go logging library πŸͺ΅
Go
2,284
star
15

skate

A personal key value store πŸ›Ό
Go
1,326
star
16

wishlist

The SSH directory ✨
Go
1,074
star
17

harmonica

A simple, physics-based animation library 🎼
Go
1,020
star
18

melt

Backup and restore Ed25519 SSH keys with seed words 🫠
Go
579
star
19

kancli

A tutorial for building a command line kanban board in Go
Go
172
star
20

vhs-action

Keep your GIFs up to date with VHS + GitHub actions πŸ“½οΈ
TypeScript
163
star
21

bubbletea-app-template

A template repository to create Bubbletea apps.
Go
131
star
22

x

Charm experimental packages
Go
125
star
23

keygen

An SSH key pair generator πŸ—οΈ
Go
109
star
24

taskcli

A tutorial for building a Taskwarrior-inspired task tracker in Go using glamorous CLI libraries
Go
97
star
25

inspo

Share and explore projects you can build with Charm libraries
93
star
26

wizard-tutorial

A basic wizard made with Bubble Tea and Lip Gloss. Follow along with the tutorial video for this project:
Go
81
star
27

tree-sitter-vhs

Syntax highlighting for VHS with tree-sitter 🌳
JavaScript
79
star
28

confettysh

confetti over ssh
Go
56
star
29

git-lfs-transfer

Server-side implementation of the Git LFS pure-SSH protocol
Go
50
star
30

catwalk

Open source 3D models from Charm 🧸
50
star
31

soft-serve-action

Synchronize GitHub repositories to your Soft Serve instance 🍦
47
star
32

promwish

Prometheus middleware for Wish
Go
41
star
33

meta

Charm's meta configuration files πŸ«₯
25
star
34

hotdiva2000

A human-readable random string generator πŸ‘‘
Go
25
star
35

homebrew-tap

Our homebrew tap 🍺
Ruby
23
star
36

scoop-bucket

Charmbracelet Scoop Bucket
15
star
37

nur

Nix
14
star
38

.github

Default community health files
2
star