Documentation
¶
Overview ¶
Package ui provides consistent terminal output primitives for the obol CLI.
Pass a *UI through your call chain instead of using fmt directly. Output adapts to the environment: colors and spinners in interactive terminals, plain text when piped or in CI.
When OutputJSON mode is active, human-readable output (Info, Success, Print, etc.) is redirected to stderr so that stdout contains only clean JSON. Use the JSON() method to emit structured data.
Index ¶
- Constants
- func Banner() string
- type ExecConfig
- type OutputMode
- type UI
- func (u *UI) Blank()
- func (u *UI) Bold(msg string)
- func (u *UI) Confirm(msg string, defaultYes bool) bool
- func (u *UI) Detail(key, value string)
- func (u *UI) Dim(msg string)
- func (u *UI) Error(msg string)
- func (u *UI) Errorf(format string, args ...any)
- func (u *UI) Exec(cfg ExecConfig) error
- func (u *UI) ExecOutput(cfg ExecConfig) ([]byte, error)
- func (u *UI) FormatActionableError(err error, action string)
- func (u *UI) FormatError(err error, hint string)
- func (u *UI) Info(msg string)
- func (u *UI) Infof(format string, args ...any)
- func (u *UI) Input(msg string, defaultVal string) (string, error)
- func (u *UI) IsJSON() bool
- func (u *UI) IsQuiet() bool
- func (u *UI) IsTTY() bool
- func (u *UI) IsVerbose() bool
- func (u *UI) JSON(v any) error
- func (u *UI) Print(msg string)
- func (u *UI) Printf(format string, args ...any)
- func (u *UI) RunWithSpinner(msg string, fn func() error) error
- func (u *UI) SecretInput(msg string) (string, error)
- func (u *UI) Select(msg string, options []string, defaultIdx int) (int, error)
- func (u *UI) Success(msg string)
- func (u *UI) Successf(format string, args ...any)
- func (u *UI) SuggestCommand(app *cli.App, command string)
- func (u *UI) Warn(msg string)
- func (u *UI) Warnf(format string, args ...any)
Constants ¶
const ( ColorObolGreen = "#2FE4AB" // Primary brand green ColorObolDarkGreen = "#0F7C76" // Dark green (success) ColorObolCyan = "#3CD2DD" // Light blue / info ColorObolPurple = "#9167E4" // Accent purple ColorObolAmber = "#FABA5A" // Warning amber ColorObolRed = "#DD603C" // Error red-orange ColorObolAcid = "#B6EA5C" // Highlight acid green ColorObolMuted = "#667A80" // Muted gray ColorObolLight = "#97B2B8" // Light muted )
Obol brand colors — from blog.obol.org/branding.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ExecConfig ¶
type ExecConfig struct {
// Name is the display name shown in the spinner (e.g., "Deploying with helmfile").
Name string
// Cmd is the command to run.
Cmd *exec.Cmd
// Interactive runs the command with stdin/stdout/stderr connected directly
// to the terminal. Use this for commands that may prompt for input (e.g. sudo).
// Disables spinner and output capture.
Interactive bool
}
ExecConfig configures how a subprocess is run.
type OutputMode ¶
type OutputMode int
OutputMode controls the format of command output.
const ( // OutputHuman is the default human-readable output mode. OutputHuman OutputMode = iota // OutputJSON produces machine-readable JSON on stdout. OutputJSON )
func ParseOutputMode ¶
func ParseOutputMode(s string) (OutputMode, error)
ParseOutputMode converts a string to an OutputMode.
type UI ¶
type UI struct {
// contains filtered or unexported fields
}
UI provides consistent terminal output primitives.
func New ¶
New creates a UI instance. When verbose is true, subprocess output is streamed live instead of captured behind a spinner.
func NewWithAllOptions ¶
func NewWithAllOptions(verbose, quiet bool, output OutputMode) *UI
NewWithAllOptions creates a UI instance with full control over all modes.
func NewWithOptions ¶
NewWithOptions creates a UI instance with full control over verbose and quiet modes. Quiet mode suppresses all output except errors.
func (*UI) Confirm ¶
Confirm asks a yes/no question, returns true for "y"/"yes". In non-interactive mode, returns the default without prompting.
func (*UI) Error ¶
Error prints: ✗ message (red x, matching obolup.sh log_error). Not suppressed by quiet mode.
func (*UI) Exec ¶
func (u *UI) Exec(cfg ExecConfig) error
Exec runs a subprocess with output capture and spinner.
Default mode (TTY, not verbose):
- Shows spinner with config.Name
- Captures stdout+stderr to buffer
- On success: "✓ Name (Xs)"
- On failure: "✗ Name" + dumps captured output to stderr
Verbose mode:
- Shows "==> Name"
- Streams stdout+stderr live, each line indented with dim "│" prefix
Non-TTY (pipe/CI):
- Shows "Name..."
- Streams live (no spinner)
func (*UI) ExecOutput ¶
func (u *UI) ExecOutput(cfg ExecConfig) ([]byte, error)
ExecOutput runs a subprocess, captures stdout, and returns it. Stderr is captured and shown on error.
func (*UI) FormatActionableError ¶
FormatActionableError renders an error with a concrete next-step command.
✗ Stack not running Run: obol stack up
func (*UI) FormatError ¶
FormatError renders a structured error with an optional hint.
✗ something went wrong Hint: check your configuration
func (*UI) Input ¶
Input reads a single line of text input with an optional default. In non-interactive mode, returns the default or an error if no default is set.
func (*UI) JSON ¶
JSON writes v as indented JSON to the real stdout (os.Stdout). This bypasses the stderr redirect so agents always get JSON on stdout.
func (*UI) RunWithSpinner ¶
RunWithSpinner executes fn while displaying a spinner with msg.
On success: replaces spinner with "✓ msg (duration)". On failure: replaces spinner with "✗ msg", caller handles error display. In verbose mode or non-TTY: prints the message and runs fn without animation.
func (*UI) SecretInput ¶
SecretInput reads input without echoing (for API keys, passwords). In non-interactive mode, returns an error directing the user to use a flag.
func (*UI) Select ¶
Select presents a numbered list and returns the selected index. In non-interactive mode, returns the default index without prompting.
func (*UI) SuggestCommand ¶
SuggestCommand prints an error for an unknown command and suggests similar commands based on Levenshtein distance.
Source Files