Skip to content

About

Interactive command prompt for use within Bubble Tea applications

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

104 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Bubblecomplete

Go Reference Latest Release CI Go Report

A polished command-prompt component for Bubble Tea. Type, Tab through suggestions, browse the filesystem inline, and hand the validated input back to the host. No parser required.

demo

Features

  • Tab cycling through commands, subcommands, flags, and positional arguments
  • Live filesystem completion for path arguments, with green / underline / red validity overlay on the typed token
  • Shell ergonomics — trailing slash on dir accepts, trailing space on file accepts, auto-quote on basenames with spaces, single-match auto-accept, drill-down on the next Tab
  • Quote-aware parsing — '…', "…", unclosed, and equals-form --flag=… all do what you'd expect
  • Persistent history — JSON-backed across sessions, with inline suggestions for last-typed commands
  • Structured validation errors — route on ValidationErrorKind, no string-matching
  • Themable — styles, key bindings, icons, and layout are all configurable

Install

go get github.com/dotopototo/bubblecomplete/v2

Defining commands

Commands are plain struct literals — no DSL, no builder. A command has either subcommands or positional arguments (never both), and any number of flags:

var commands = []*bubblecomplete.Command{
    {
        Command:     "cp",
        Description: "Copy files and directories",
        PositionalArguments: []*bubblecomplete.PositionalArgument{
            {Name: "source", Type: bubblecomplete.FileDirArgument, Required: true},
            {Name: "dest",   Type: bubblecomplete.DirArgument,     Required: true},
        },
        Flags: []*bubblecomplete.Flag{
            {ShortFlag: "-r", Description: "Recursive", Type: bubblecomplete.BoolArgument},
        },
    },
}

Argument types: StringArgument, IntArgument, FloatArgument, BoolArgument, FileArgument, DirArgument, FileDirArgument. Flags can be short (-v), long (--verbose), or PowerShell-style (-Verbose), and may be marked Persistent: true to propagate to subcommands. See the godoc for the full struct surface.

Usage

Embed the component in your Bubble Tea model and forward Update / View:

import (
    "log"

    tea "charm.land/bubbletea/v2"
    "github.com/dotopototo/bubblecomplete/v2"
)

type model struct {
    bc bubblecomplete.Model
}

func initialModel() tea.Model {
    bc, err := bubblecomplete.New(commands, 100,
        bubblecomplete.WithFilesystemCompletions(true),
        bubblecomplete.WithHistoryLimit(50),
    )
    if err != nil {
        log.Fatal(err)
    }
    return model{bc: bc}
}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    var cmd tea.Cmd
    m.bc, cmd = m.bc.Update(msg)
    if sel, ok := msg.(bubblecomplete.SelectedCommandMsg); ok {
        // sel.Command is the validated input; sel.Err is non-nil on validation failure.
        _ = sel
    }
    return m, cmd
}

func (m model) View() tea.View { return m.bc.View() }

A complete runnable program lives in ./example — go run ./example to try it.

Filesystem completions

Turn it on with WithFilesystemCompletions(true). As the user types a value for a FileArgument, DirArgument, or FileDirArgument, the completion list shows real filesystem entries from the relevant parent directory — directories first (with trailing /), then files, sorted case-fold. Tab cycles, Shift+Tab reverses, Right (or any keystroke) accepts. Single matches auto-accept, and a second Tab drills into the just-accepted directory — matching standard shell tab-completion behaviour.

The typed value gets a validity overlay:

State Meaning
green resolves to an entry of the expected kind
underlined strict prefix of one or more existing entries (mid-navigation)
red doesn't resolve, or resolves to the wrong kind

Invariant: when the overlay is shown, green means Enter accepts. The classifier and submit-time validator share a resolver, so the colour can't lie about whether submitting would succeed. (The overlay is suppressed in a few documented cases — wide inputs that overflow the terminal, file cycling — where Enter still behaves correctly but the colour is absent.)

Tilde expansion (~, ~/), quote handling ("…", '…', equals-form --path="…"), auto-quote on basenames with spaces, and a subtle + N more footer when the directory exceeds the candidate limit are all built in. Full behaviour, limits, and caveats live in the godoc.

Configuration

Common options:

Option Default Description
FilesystemCompletions false Opt into live filesystem completion + validity overlay
HistoryLimit 100 Max history entries; ≤ 0 disables history
HistoryFilePath — JSON file for history persistence (via WithHistoryFilePath / SetHistoryFilePath)
ShowIcons false Type-indicator icons on each row
ShowDescriptions true Render the description column
CompletionRows 5 Visible rows before scrolling
…and more — Layout, scrollbar, icon glyphs, hidden files, candidate cap — see Model godoc

Every option has a matching With* construction function, and most are also mutable public fields on Model for runtime tweaks. Styles and key bindings live on their respective accessors: Styles() / SetStyles and KeyMap() / SetKeyMap.

Roadmap

  • PowerShell flag aliases (e.g. -v for -Verbose)
  • Mutually-exclusive flags
  • Pluggable completion provider (for dynamic / remote sources)

Non-Goals

Bubblecomplete is a prompt component, not a shell. Don't expect:

  • Executing commands — the component hands the submitted string back via SelectedCommandMsg and the host runs it
  • Full POSIX shell parsing (substitution, here-docs, redirections)
  • Shell alias resolution
  • Environment variable expansion ($HOME, ${FOO})
  • Glob expansion (*.go)

FAQ

Why do colours look off? Bubble Tea components render best in 24-bit terminals. Make sure your terminal (and tmux config, if applicable) advertises truecolor — $TERM=xterm-256color and $COLORTERM=truecolor.

Is Model goroutine-safe? No, and intentionally so. Bubble Tea runs Update on a single goroutine and all state changes happen there. Background work should return tea.Msg values for the next Update to consume — never mutate Model from another goroutine.

License

MIT

About

Interactive command prompt for use within Bubble Tea applications

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages