A powerful Starlark module for building Terminal User Interfaces (TUI), inspired by charmbracelet/gum, huh, and bubbletea. Create beautiful, interactive command-line interfaces in your Starlark scripts.
Within the Star* ecosystem, starpkg provides support for necessary local operations plus simple abstractions over common online services, for ease of use. gum is squarely a local capability: it drives the host's own terminal — prompts, selections, spinners, Markdown rendering, gradient text — and touches no network service. It is an L4 domain module that depends downward on starpkg/base (the module/config system) and 1set/starlet (the Machine runner), and transitively 1set/starlight + go.starlark.net.
- Text Input: Single and multi-line text inputs with validation
- Selection: Single and multi-option selection components
- Confirmation: Yes/No prompts with customizable text
- File Picking: Navigate and select files and directories
- Visual Elements: Spinners, notes, and colorized text output
- Theming Support: Multiple built-in themes (Charm, Dracula, Catppuccin, etc.)
- Customization: Configure width, height, timeouts, and more
go get github.com/starpkg/gumpackage main
import (
"fmt"
"github.com/1set/starlet"
"github.com/starpkg/gum"
)
func main() {
// Create a new gum module with default settings.
gumModule := gum.NewModule()
// Create a Starlet interpreter with the module.
interpreter := starlet.New(
starlet.WithModuleLoader("gum", gumModule.LoadModule()),
)
// Run a Starlark script with TUI components.
script := `
load("gum", "input", "select", "confirm")
name = input(title = "What's your name?", placeholder = "Enter your name")
color = select(options = ["Red", "Green", "Blue"], title = "Choose a color:")
ok = confirm(title = "Is this correct?", description = "Name: " + name + "\nColor: " + color)
print("Confirmed:", ok)
`
// Execute the script.
if err := interpreter.ExecScript("example.star", script); err != nil {
fmt.Println("Error:", err)
}
}A self-contained script example:
load("gum", "input", "confirm", "colorize")
def validate_name(name):
if len(name) < 3:
return "Name must be at least 3 characters long"
return None
name = input(title = "Welcome!", placeholder = "John Doe", validate = validate_name)
if name != None:
print(colorize("Hello, " + name + "!", pattern = "RainbowBlue"))
if confirm(title = "Continue?", yes = "Let's go!", no = "Not now"):
print("Starting process...")Load builtins with load("gum", ...). Every builtin is listed below; see
docs/API.md for the full reference — signatures,
parameters, returns, errors, and examples.
| Builtin | Summary |
|---|---|
input |
Single-line text input, with validation, suggestions, and password/echo modes. |
write |
Multi-line text area, with optional external editor support. |
select |
Single-selection from a list or dict of options. |
multi_select |
Multi-selection with an optional selection limit. |
filter |
Fuzzy-filter a list as you type (single or multi-select). |
confirm |
Yes/No confirmation dialog. |
file_pick |
File/directory picker with extension and visibility filters. |
note |
Display an informational note with a title and description. |
md |
Render Markdown to ANSI terminal text (non-interactive). |
md_note |
Render Markdown and display it in a TUI note. |
spin |
Show a spinner, optionally running an action while it spins. |
colorize |
Colorize text with a solid color or a gradient (non-interactive). |
code_block |
Syntax-highlight source code to ANSI via chroma (non-interactive). |
style |
Render styled text — colors, attributes, border, padding (non-interactive). |
table |
Render a bordered table from headers and rows (non-interactive). |
tree |
Render a nested tree from a dict/list (non-interactive). |
compose |
Join rendered blocks into a layout, horizontally or vertically (non-interactive). |
set_theme |
Set the active theme and re-apply it immediately. |
TTY note. The interactive builtins drive the host's controlling terminal and fail with
could not open a new TTYin headless environments (CI, sandboxes).md,colorize,code_block,style,table,tree, andcomposeare non-interactive and run anywhere.
The gum module is configured through starpkg/base: options width,
height, theme, and editor, each with an environment variable (GUM_<KEY>).
width/height/theme expose an auto-generated get_<key> / set_<key>
script accessor pair; editor is host-only (it names the command write
runs via os/exec, so a script gets a read-only get_editor but no
set_editor and cannot choose it). See
docs/API.md → Configuration for the full table
and the Go constructors (NewModule, NewModuleWithConfig).
This package is licensed under the MIT License - see the LICENSE file for details.
Go 1.25.8 or newer is required. Release builds use Go 1.27.1. The Unicode dependency includes the reviewed fix. The interpreter stays at ffb3f39dd27a and retains its known parser recursion limitation; parse only host-reviewed source in-process.