README
¶
Prism
Build beautiful command-line tools in Go, without the boilerplate. A component library for consistent output styling, tables, spinners, progress bars, and interactive prompts. Import it into any Go project and ship a polished CLI in an afternoon.
go get github.com/velocitykode/prism
import "github.com/velocitykode/prism"
Prism has zero framework dependency. Use it in any Go program, Velocity or not. It is built on the Charm stack (lipgloss, bubbletea, bubbles).
Why Prism
- Consistent by default. Leveled output, boxes, and prompts share one theme, so your whole tool looks intentional.
- Batteries included. Output, tables, spinners, progress bars, and seven prompt types in one import.
- One-liners. Each helper is a single call that returns a typed result; no models, no event loops to wire up.
- Drop-in anywhere. No framework lock-in, no global state.
Output
prism.Header("migrate") // MIGRATE (styled header)
prism.Info("Running migrations...") // informational line
prism.Success("Done") // checkmark, success color
prism.Warning("No migrations found") // warning glyph and color
prism.Error("Connection failed") // error glyph and color
prism.Muted("skipping...") // dimmed text
prism.Bold("important") // bold text
prism.Note("Server running on port 4000") // boxed message (primary border)
prism.Alert("Database connection failed") // boxed message (error border)
Tables
prism.Table(
[]string{"Method", "Path", "Name"},
[][]string{
{"GET", "/users", "users.index"},
{"POST", "/users", "users.store"},
},
)
Spinners & Progress
A spinner wraps a slow step; a progress bar tracks a known count:
prism.Spinner("Building...", func() error {
return exec.Command("go", "build", ".").Run()
})
prism.Progress(len(items), func(inc func()) {
for _, item := range items {
process(item)
inc()
}
})
Interactive Prompts
Each prompt blocks for input and returns the typed result:
name := prism.Text("Model name:", prism.WithRequired(), prism.WithPlaceholder("User"))
pass := prism.Password("Database password:")
yes := prism.Confirm("Generate migration?", prism.WithDefaultYes())
db := prism.Select("Database driver:", []string{"mysql", "postgres", "sqlite"})
features := prism.Multiselect("Enable:", []string{"soft-deletes", "uuid", "timestamps"})
user := prism.Search("Find user:", func(q string) []string {
return filterUsers(q)
})
Theming
Output colors and prompt styling are driven by a shared theme, so a whole tool stays visually consistent. Override it to match your brand.
Built On
- charmbracelet/lipgloss - styling
- charmbracelet/bubbletea - interactive prompts
- charmbracelet/bubbles - prebuilt components
License
MIT
Documentation
¶
Index ¶
- func Alert(message string)
- func Bold(message string)
- func Configure(cfg Config)
- func Confirm(label string, opts ...ConfirmOption) bool
- func Error(message string)
- func ExitOnCancel(m any)
- func Header(message string)
- func Highlight(text string) string
- func Info(message string)
- func KeyValue(key, value string)
- func LoadConfig(r io.Reader) error
- func Multiselect(label string, options []string) []string
- func Muted(message string)
- func Newline()
- func NextSteps(steps []string)
- func Note(message string)
- func Password(label string) string
- func Progress(total int, fn func(increment func()))
- func ResetConfig()
- func Search(label string, fn func(query string) []string) string
- func Select(label string, options []string, opts ...SelectOption) string
- func SetCancelHandler(fn func())
- func SetWriter(w io.Writer)
- func Spinner(message string, fn func() error) error
- func Step(message string)
- func StyleError(text string) string
- func StyleMuted(text string) string
- func StylePrimary(text string) string
- func StyleSuccess(text string) string
- func StyleWarning(text string) string
- func Success(message string)
- func Table(headers []string, rows [][]string)
- func Text(label string, opts ...TextOption) string
- func Tip(message string)
- func Warning(message string)
- type Canceller
- type Colors
- type Config
- type ConfirmOption
- type SelectOption
- type Symbols
- type TextOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Alert ¶
func Alert(message string)
Alert prints a message in a rounded box with error-colored border.
func Configure ¶
func Configure(cfg Config)
Configure merges cfg into the active config and rebuilds all styles. Empty string fields are ignored (they keep the current value), so callers can override just the fields they care about.
func Confirm ¶
func Confirm(label string, opts ...ConfirmOption) bool
Confirm displays a yes/no prompt and returns the user's choice.
func ExitOnCancel ¶
func ExitOnCancel(m any)
func LoadConfig ¶
LoadConfig reads TOML config from r and applies it. Missing fields keep defaults. The caller owns the file - open with os.Open, pass the *os.File, close it yourself.
func Multiselect ¶
Multiselect displays a list of options with toggles and returns all selected options.
func Note ¶
func Note(message string)
Note prints a message in a rounded box with primary-colored border.
func Progress ¶
func Progress(total int, fn func(increment func()))
Progress displays an animated progress bar for batch operations. The fn receives an increment function to call after each completed item.
func Search ¶
Search displays a text input that filters results dynamically. The fn is called with the current query and should return matching options.
func Select ¶
func Select(label string, options []string, opts ...SelectOption) string
Select displays a list of options and returns the selected one.
func SetCancelHandler ¶
func SetCancelHandler(fn func())
SetCancelHandler registers a callback invoked right before the process exits on cancel. Pass nil to restore the default (exit only). The callback should be cheap and non-blocking; it runs inside the prompt's return path.
func SetWriter ¶
SetWriter sets the output writer for all non-interactive components. Pass nil to fall back to os.Stdout (resolved dynamically at each call).
func Spinner ¶
Spinner displays an animated spinner while fn executes. Returns the error from fn, if any.
Without an interactive terminal (CI, headless, piped output) the bubbletea program cannot open /dev/tty and p.Run would fail, masking fn's result entirely. In that case Spinner degrades to a plain one-line message and runs fn directly, so the wrapped work still executes and its real error is returned unchanged.
func StylePrimary ¶
StylePrimary renders text in the primary brand color (same as Highlight).
func StyleSuccess ¶
StyleSuccess renders text in the success color.
func StyleWarning ¶
StyleWarning renders text in the warning color.
func Text ¶
func Text(label string, opts ...TextOption) string
Text displays a single-line text input and returns the entered value.
Types ¶
type Canceller ¶
type Canceller interface {
Cancelled() bool
}
Canceller is implemented by interactive prompt models that can be cancelled via Ctrl+C or Esc. Implementations return true once the user has signalled a cancel.
type Colors ¶
type Colors struct {
Primary string `toml:"primary"`
Success string `toml:"success"`
Warning string `toml:"warning"`
Error string `toml:"error"`
Muted string `toml:"muted"`
}
Colors are hex strings like "#0e87cd" or named ANSI colors accepted by lipgloss.
type Config ¶
Config controls colors and symbols used by all output and prompt components. Empty string fields are ignored by Configure - they keep the current value.
type ConfirmOption ¶
type ConfirmOption func(*confirmConfig)
ConfirmOption configures a Confirm prompt.
type SelectOption ¶
type SelectOption func(*selectConfig)
SelectOption configures a Select prompt.
func WithSelectDefault ¶
func WithSelectDefault(val string) SelectOption
WithSelectDefault sets the initially highlighted option.
type Symbols ¶
type Symbols struct {
Arrow string `toml:"arrow"`
Check string `toml:"check"`
Warn string `toml:"warn"`
Cross string `toml:"cross"`
Tip string `toml:"tip"`
}
Symbols are the glyphs used by Info (arrow), Success (check), Warning (warn), Error (cross), and Tip (info glyph).
type TextOption ¶
type TextOption func(*textConfig)
TextOption configures a Text prompt.
func WithDefault ¶
func WithDefault(s string) TextOption
WithDefault sets a default value pre-filled in the input.
func WithPlaceholder ¶
func WithPlaceholder(s string) TextOption
WithPlaceholder sets placeholder text shown when input is empty.
func WithValidation ¶
func WithValidation(fn func(string) error) TextOption
WithValidation sets a validation function.
Source Files