charmbracelet/gum
63.1
Adequate · 13 November 2026
5.1k
lines of production code
Go
primary language
7
measurements over time
What this system is
Gum is a command-line interface toolkit that provides a comprehensive suite of interactive terminal user interface (TUI) components for shell scripting. It enables users to build rich, stylized terminal experiences by offering commands for text input, selection, filtering, formatting, and data visualization. The system integrates with the Charm ecosystem to deliver consistent styling and behavior across various interactive elements like tables, spinners, and file pickers.
How it got here
2022 — Gum v2 rewrite and command expansion
21 changes.
The project underwent a complete rewrite to Gum v2, migrating to the Charm v2 ecosystem and Bubble Tea v2 to replace the legacy implementation. This period focused on introducing a comprehensive suite of new commands—including input, filter, table, and file selection—while establishing internal utilities for stdin processing, exit codes, and file handling.
2023–2024 — CLI utility and logging enhancements
4 changes.
This period focused on expanding the library's core utilities with new commands for structured logging, version constraint checking, and TTY-aware output handling. It also introduced customizable cursor visibility and blinking modes for text input components to improve interactive user experience.
Features
Add \`gum join\` command for combining text layouts
Users can now use the new \gum join\ command to combine multi-line text strings horizontally or vertically, leveraging the lipgloss library for layout. The command accepts text arguments and allows configuration of alignment (left, center, right, bottom, middle, top) and orientation (horizontal or vertical), enabling users to build complex layouts such as placing bordered boxes side-by-side or stacked.
join · high confidence
Add man page generation subcommand
Users can now generate manual pages for the tool by using the new 'man' subcommand. This feature adds a dedicated command handler that utilizes the mango-kong library to build a roff-formatted man page, including a specific description and copyright section, and outputs it to stdout.
man · high confidence
Add shell autocompletion for Bash, Zsh, and Fish
Users can now generate shell autocompletion scripts for Bash, Zsh, and Fish via the new completion command. This feature introduces dedicated generators for each shell, allowing the CLI to provide context-aware suggestions for commands and flags, including support for enum values and file/directory filtering directives.
completion · high confidence
Add version constraint checking command
Users can now verify that the current application version satisfies a specific semantic version constraint via a new command. This feature parses the provided constraint and the current version number, returning an error if the current version does not fall within the specified range.
version · high confidence
Cursor visibility and blinking modes for text inputs
The cursor package now exposes functions to control cursor appearance in text input and text area components. Users can specify a mode (hide, blink, or static) to determine whether the cursor is visible and whether it blinks, with the cursor color automatically matching the current foreground style. This allows for more consistent and customizable cursor behavior across interactive text fields.
cursor · high confidence
Gum v2: Complete rewrite with new commands and Bubble Tea v2
Gum has been rewritten for v2, replacing the previous 'Soda Pop' implementation with a comprehensive suite of new commands including choose, confirm, file, filter, format, join, pager, table, write, and log. The application now leverages Bubble Tea v2 and Lip Gloss v2 for its UI components, and introduces a new version flag for displaying build information. This release also adds support for Nix flakes, Docker containers, and various package managers (Scoop, WinGet, Flox), while removing the legacy pop.go interface.
(repo-wide) · high confidence
Introduce \`gum format\` command for text styling and rendering
Users can now use the new \gum format\ command to render text in four distinct modes: Markdown, Code, Emoji, and Template. The command accepts input via arguments or stdin and allows customization through the \--type\ flag, a configurable Glamour theme (defaulting to 'pink' via the \GUM\_FORMAT\_THEME\ environment variable), and a specific programming language for code syntax highlighting (via the \GUM\_FORMAT\_LANGUAGE\ environment variable). Template mode leverages Termenv and Lipgloss to apply styling functions like bold, italic, and color directly within the input string.
format · high confidence
Introduce \`gum input\` command for text input
Adds a new \gum input\ command that provides a shell-script interface for the text input bubble, allowing users to prompt for and capture text input. The command supports configuring the prompt, placeholder, and header text (with custom styling), setting an initial value or reading from stdin, masking input as a password, limiting character count, and adjusting width (including auto-resizing to terminal width). It also handles timeouts, ANSI stripping from stdin, and exposes help keybindings.
input · high confidence
Introduce \`gum style\` command for text styling
Adds a new \gum style\ command that applies Lip Gloss styling to text input. Users can pass text directly as arguments or pipe it via stdin, with options to control colors, borders, alignment, padding, and margins. The command also supports trimming whitespace from input lines and optionally stripping ANSI sequences when reading from standard input.
style · high confidence
Introduce \`gum table\` for interactive CSV selection
Adds a new \table\ command that renders CSV data (from stdin or a file) into an interactive terminal table, allowing users to select a row and return the result. The command supports static printing via the \--print\ flag, customizable column widths, borders, and styles, and handles CSV nuances like BOM stripping, lazy quotes, and field counts. When interactive, it uses the bubbletea framework to let users navigate and select rows, with options to return a specific column or the whole row, and respects timeouts and help keybindings.
table · high confidence
Introduce gum confirm command with interactive confirmation prompt
The confirm command is now available, allowing users to prompt for an affirmative or negative action via an interactive TUI. Users can customize the prompt text, affirmative/negative labels, default selection, and styling (including padding and colors). The command supports keyboard shortcuts (y/n, arrows, enter, esc, ctrl+c), displays help keys, and respects a configurable timeout. It exits with code 0 for affirmative and 1 for negative/abort, and optionally prints the prompt and chosen action to stdout when --show-output is enabled.
confirm · high confidence
Introduce gum file command for interactive file selection
The new \gum file\ command provides an interactive, tree-like interface for users to navigate directories and select files or folders. It leverages the \charm.land/bubbles/v2/filepicker\ library to render a customizable file browser, supporting options to toggle file/directory selection, display permissions and sizes, show hidden files, and apply custom styling to cursors, symlinks, and directories. The command respects timeout settings and outputs the selected path to standard output.
file · high confidence
Introduce gum filter command with multi-select and fuzzy search
The \gum filter\ command is now available, providing a fuzzy-searchable text input for filtering lists of options. It supports multi-select via flags like \--limit\ and \--no-limit\, pre-selection of items with \--selected\, and customizable styling for headers, placeholders, and match highlighting. The command handles input from STDIN or files, supports fuzzy and exact matching modes, and includes keybindings for navigation, toggling selections, and aborting.
filter · high confidence
Introduce gum pager for terminal text viewing
Adds a new \gum pager\ command that provides a \less\-like experience for scrolling through long documents or stdin content in the terminal. The pager supports soft-wrapping (enabled by default), line numbers, and regex-based search with match highlighting. It includes keyboard navigation (up/down, home/end, search with n/p for next/previous matches) and respects timeout settings, integrating with the gum v2 style system for consistent theming.
pager · high confidence
Introduce gum spin command for background task indication
Adds a new \spin\ command that runs a shell command in the background while displaying a configurable spinner and title. The command supports showing live stdout/stderr output, handling timeouts, and preserving terminal colors when piping. It uses the new \charm.land/bubbles/v2/spinner\ and \charm.land/bubbletea/v2\ libraries, with styling controlled via \--spinner\, \--title\, and \--padding\ flags, and environment variables like \GUM\_SPIN\_SHOW\_OUTPUT\.
spin · high confidence
Introduce gum write command for multi-line text input
Adds a new \gum write\ command that provides a shell-script interface for multi-line text input using a Bubble Tea textarea. Users can enter long-form text which is output to stdout upon submission (Enter), with options to abort via Ctrl+C or Escape. The command supports configuring the textarea's dimensions, character limits, line numbers, cursor mode, and styling, as well as setting an initial value via stdin or the \--value\ flag.
write · high confidence
Introduce the log command for structured text logging
Users can now use the new 'log' command to output text with configurable levels (debug, info, warn, error, fatal), formatters (text, json, logfmt), and styling. The command supports writing to files, setting minimum log levels via the GUM\_LOG\_LEVEL environment variable, and customizing the appearance of timestamps, prefixes, and message components through style options.
log · high confidence
Introduce tty-aware output writer with ANSI stripping
The internal/tty package now provides a Writer function that returns an io.Writer for stdout, automatically handling ANSI sequence stripping or downgrading based on environment variables (NO\_COLOR, CLICOLOR, CLICOLOR\_FORCE) and terminal capabilities. This ensures consistent output formatting across different terminal environments by leveraging the colorprofile library.
internal/tty · high confidence
Introduces dedicated exit codes and timeout context handling
The application now provides specific exit codes for timed out commands (124) and aborted commands (130) via the new internal/exit package, along with a custom ErrExit error type. Additionally, the internal/timeout package has been added to manage context timeouts, allowing commands to be configured with a specific duration after which they will automatically terminate.
internal/exit · high confidence
New examples directory with shell scripts and test tapes
The repository now includes an \examples/\ directory containing a collection of shell scripts demonstrating \gum\ usage, such as \commit.sh\ for conventional commits, \git-branch-manager.sh\ for branch operations, \diyfetch\ for system info display, and integration examples for Node.js, Python, and Ruby. Each script is accompanied by \.tape\ files that define automated test sequences to generate GIF demonstrations, along with supporting assets like \README.md\ and \.gitignore\ for generated media.
examples · high confidence
New internal file-listing utility with default ignore patterns
Added a new \internal/files\ package that provides a \List()\ function to retrieve all files in the current directory. This utility automatically excludes \node\_modules\, \.git\, and the current directory (\.\) from the results, offering a consistent way for other parts of the application to access file listings without manually handling these common exclusions.
internal/files · high confidence
New internal package for configurable stdin input processing
Added a new \internal/stdin\ package that provides a \Read\ function for processing input from stdin pipes. This function supports configurable options to read either a single line or the full input, and includes an optional feature to strip ANSI escape sequences from the text. It also provides an \IsEmpty\ helper to detect when stdin is empty or not a pipe.
internal/stdin · high confidence
Behavioural changes
Added text alignment mapping for lipgloss v2
The internal decode package now includes a new align.go file that maps string values (center, left, top, bottom, right) to lipgloss.Position types from the newly adopted charm.land/lipgloss/v2 library, enabling consistent text alignment handling within the decode logic.
internal/decode · high confidence
Introduce gum choose v2 with multi-select, pagination, and keybindings
The \gum choose\ command has been rewritten for v2, replacing the previous Huh-based implementation with a custom Bubble Tea model. This update adds multi-select capabilities (controlled by \--limit\ or \--no-limit\), a paginator for navigating long lists, and new keybindings such as \g\/\G\ for jumping to the start/end, \a\/\A\ for selecting all, and \ctrl+j\/\ctrl+k\ for navigation. It also introduces label delimiters (\--label-delimiter\), pre-selection via \--selected\, and consistent timeout and interrupt handling.
choose · high confidence
Dependencies
Upgrade to Gum v2 with Charm v2 ecosystem dependencies
The project module path has been updated to charm.land/gum/v2 and the Go version requirement raised to 1.26.7. Core dependencies have been migrated to the Charm v2 ecosystem, including bubbletea (v2.0.10), bubbles (v2.1.1), lipgloss (v2.0.5), and glamour (v2.0.1). The argument parser has been upgraded from kong v0.6.1 to v1.15.0, and the fuzzy search library to v0.1.3. Additional dependencies such as x/ansi (v0.11.7), x/term (v0.2.2), and semver (v3.5.0) have been added or updated to support the new version.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 65 → 63 (-1.5)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.3) — scores are not directly comparable.
Lenses
- Code Health 75 → 75 (+0.0)
- Architecture 99 → 99 (-0.4)
- Maturity 52 → 50 (-2.1)
- Readiness 71 → 71 (+0.0)
- Security 82 → 76 (-6.1)
Resolved (2)
- Hotspot: log/command.go (log/command.go)
- No ADRs found
New (7)
- Edited copies of one member (3 members, 10+ corresponding lines) (file/file.go)
- Edited copies of one member (3 members, 13+ corresponding lines) (format/formats.go)
- Edited copies of one member (3 members, 19+ corresponding lines) (file/file.go)
- Edited copy of a member (18 corresponding lines) (style/lipgloss.go)
- Edited copy of a member (22 corresponding lines) (filter/filter.go)
- Edited copy of a member (37 corresponding lines) (pager/search.go)
- No ADRs found (gum.go)
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
charmbracelet/gum was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 13 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 879f048103adf0214b85943b52d8d65b08d772c5 — the exact code this score is about.
- Scored under rubric-2026.11.3 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.61+preprod-f3449e6eb431.