ui

package
v0.10.0-rc17 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 12, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

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

View Source 
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 

func Banner() string

Banner returns the Obol Stack ASCII art rendered in brand colors.

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 added in v0.8.0 

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 added in v0.8.0 

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 

func New(verbose bool) *UI

New creates a UI instance. When verbose is true, subprocess output is streamed live instead of captured behind a spinner.

func NewForTest added in v0.10.0 

func NewForTest(stdout, stderr io.Writer) *UI

NewForTest creates a UI instance that writes to the supplied writers. Use bytes.Buffer for stdout/stderr to capture output in unit tests.

func NewWithAllOptions added in v0.8.0 

func NewWithAllOptions(verbose, quiet bool, output OutputMode) *UI

NewWithAllOptions creates a UI instance with full control over all modes.

func NewWithOptions 

func NewWithOptions(verbose, quiet bool) *UI

NewWithOptions creates a UI instance with full control over verbose and quiet modes. Quiet mode suppresses all output except errors.

func (*UI) Blank 

func (u *UI) Blank()

Blank prints an empty line.

func (*UI) Bold 

func (u *UI) Bold(msg string)

Bold prints bold text.

func (*UI) Confirm 

func (u *UI) Confirm(msg string, defaultYes bool) bool

Confirm asks a yes/no question, returns true for "y"/"yes". In non-interactive mode, returns the default without prompting.

func (*UI) Detail 

func (u *UI) Detail(key, value string)

Detail prints an indented key-value pair: " key: value".

func (*UI) Dim 

func (u *UI) Dim(msg string)

Dim prints dimmed/gray text for secondary information.

func (*UI) Error 

func (u *UI) Error(msg string)

Error prints: ✗ message (red x, matching obolup.sh log_error). Not suppressed by quiet mode.

func (*UI) Errorf 

func (u *UI) Errorf(format string, args ...any)

Errorf prints a formatted error message.

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 

func (u *UI) FormatActionableError(err error, action string)

FormatActionableError renders an error with a concrete next-step command. 

✗ Stack not running
  Run: obol stack up

func (*UI) FormatError 

func (u *UI) FormatError(err error, hint string)

FormatError renders a structured error with an optional hint. 

✗ something went wrong
  Hint: check your configuration

func (*UI) Info 

func (u *UI) Info(msg string)

Info prints: ==> message (blue arrow, matching obolup.sh log_info).

func (*UI) Infof 

func (u *UI) Infof(format string, args ...any)

Infof prints a formatted info message.

func (*UI) Input 

func (u *UI) Input(msg string, defaultVal string) (string, error)

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) InputWithSuffix added in v0.10.0 

func (u *UI) InputWithSuffix(msg, defaultVal, suffix string) (string, error)

InputWithSuffix reads input like Input but renders an extra dimmed suffix between the default brace and the colon. Use this for hints that aren't part of the question itself — e.g. "[5] (5 OBOL ceiling):". The suffix is shown only when defaultVal is non-empty (so it stays adjacent to the "[default]" chip).

func (*UI) IsJSON added in v0.8.0 

func (u *UI) IsJSON() bool

IsJSON returns whether JSON output mode is active.

func (*UI) IsQuiet 

func (u *UI) IsQuiet() bool

IsQuiet returns whether quiet mode is enabled.

func (*UI) IsTTY 

func (u *UI) IsTTY() bool

IsTTY returns whether stdout is an interactive terminal.

func (*UI) IsVerbose 

func (u *UI) IsVerbose() bool

IsVerbose returns whether verbose mode is enabled.

func (*UI) JSON added in v0.8.0 

func (u *UI) JSON(v any) error

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) Print 

func (u *UI) Print(msg string)

Print writes a plain message to stdout (no prefix, no color).

func (*UI) Printf 

func (u *UI) Printf(format string, args ...any)

Printf writes a formatted message to stdout.

func (*UI) RunWithSpinner 

func (u *UI) RunWithSpinner(msg string, fn func() error) error

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 

func (u *UI) SecretInput(msg string) (string, error)

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 

func (u *UI) Select(msg string, options []string, defaultIdx int) (int, error)

Select presents a numbered list and returns the selected index. In non-interactive mode, returns the default index without prompting.

func (*UI) Success 

func (u *UI) Success(msg string)

Success prints: ✓ message (green check, matching obolup.sh log_success).

func (*UI) Successf 

func (u *UI) Successf(format string, args ...any)

Successf prints a formatted success message.

func (*UI) SuggestCommand 

func (u *UI) SuggestCommand(app *cli.App, command string)

SuggestCommand prints an error for an unknown command and suggests similar commands based on Levenshtein distance.

func (*UI) Warn 

func (u *UI) Warn(msg string)

Warn prints: ! message (yellow bang, matching obolup.sh log_warn). Not suppressed by quiet mode.

func (*UI) Warnf 

func (u *UI) Warnf(format string, args ...any)

Warnf prints a formatted warning message.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.