Documentation
¶
Overview ¶
Package ui is the single, cohesive presentation layer for the civitai CLI.
Everything user-facing that wants color, glyphs, or a spinner goes through here so the rules live in ONE place:
- Color is configured exactly once, from the root command's PersistentPreRunE, via Configure. Precedence (highest first): --no-color / NO_COLOR (force OFF) > --color / CLICOLOR_FORCE (force ON) > auto (ON only when the target writer is a real TTY and TERM != "dumb").
- The force overrides are ABSOLUTE and stream-independent. The auto case is resolved PER-WRITER: color is enabled for exactly the streams that are a real terminal. So a piped stdout with a still-TTY stderr yields plain stdout AND colored stderr — the bare helpers render against stdout (the configured default writer), a Printer/Styler renders against the writer it is bound to. See EnabledFor.
- The styled-string helpers (Success, Warn, ErrorMsg, Info, Bold, Dim, URL, Code) RETURN strings so call sites keep using fmt.Fprintf and output stays composable + testable. When color is disabled every helper returns PLAIN text — the glyph prefixes stay (they are meaningful ASCII/Unicode) but NO ANSI escape ever leaks (guaranteed by an Ascii lipgloss color profile).
- Machine-readable output (--json / --quiet / any structured path) must NOT go through these helpers. See CONVENTION.md.
Configure is safe to call once at startup; the helpers are safe to call from any goroutine afterwards (guarded by an RWMutex). If Configure is never called the helpers behave as if disabled (plain text) — the safe default.
Index ¶
- func Bold(s string) string
- func Code(s string) string
- func Configure(o Options)
- func Dim(s string) string
- func Enabled() bool
- func EnabledFor(w io.Writer) bool
- func ErrorMsg(s string) string
- func Info(s string) string
- func IsTTY(w io.Writer) bool
- func Spinner() spinner.Model
- func Success(s string) string
- func URL(s string) string
- func Warn(s string) string
- func WithSpinner(ctx context.Context, w io.Writer, message string, ...) error
- type Options
- type Printer
- type Styler
- func (s Styler) Bold(str string) string
- func (s Styler) Code(str string) string
- func (s Styler) Dim(str string) string
- func (s Styler) ErrorMsg(str string) string
- func (s Styler) Info(str string) string
- func (s Styler) Success(str string) string
- func (s Styler) URL(str string) string
- func (s Styler) Warn(str string) string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Configure ¶
func Configure(o Options)
Configure resolves the color mode from opts + environment and records the bare-helper default writer. Call it once, early (the root PersistentPreRunE). Precedence:
--no-color / NO_COLOR → OFF (highest) --color / CLICOLOR_FORCE → ON auto: per-writer TTY (TERM != "dumb")
func Enabled ¶
func Enabled() bool
Enabled reports whether styled output is on for the configured default writer (stdout). Prefer EnabledFor(w) when the destination stream matters.
func EnabledFor ¶ added in v0.1.55
EnabledFor reports whether styled (colored) output is enabled for the specific writer w. The force modes are absolute; in auto mode the answer is w's TTY-ness — so color follows each stream independently (piped stdout off, TTY stderr on).
func IsTTY ¶
IsTTY reports whether w is a terminal we can animate on. Exposed so callers (and the dev-tunnel wait) share one definition of "animatable".
func Spinner ¶
Spinner returns a bubbles spinner model pre-styled to match the CLI's accent. Callers embed it in their own bubbletea models (e.g. the dev-tunnel wait); simple "spin while doing X" sites should use WithSpinner instead. The accent is resolved against the default writer (stdout) — the spinner only animates on a TTY, and --no-color forces it plain.
func WithSpinner ¶
func WithSpinner(ctx context.Context, w io.Writer, message string, work func(context.Context) error) error
WithSpinner runs work while showing a spinner + message, for simple "spin while doing X" call sites (e.g. an upload with a network wait).
Behavior by destination:
- TTY (w is a real terminal): a bubbletea program renders a live spinner next to message while work runs on its own goroutine. The program tears down cleanly the instant work returns (or ctx is canceled). Ctrl-C cancels the context passed to work and returns promptly.
- non-TTY (piped / CI / a bytes.Buffer in tests): prints a single plain "message…" line, runs work, and returns. NO bubbletea, NO animation.
It always returns work's error (or the context error if work was interrupted and returned nil). work MUST honor its context for Ctrl-C to be prompt.
Types ¶
type Options ¶
type Options struct {
// NoColor is the resolved --no-color flag (force color OFF).
NoColor bool
// ForceColor is the resolved --color flag (force color ON even off a TTY).
ForceColor bool
// Writer is where the bare helpers' output goes; the auto path enables their
// color only when this is a real terminal. Typically os.Stdout. A Printer or
// Styler bound to a different stream resolves auto against THAT stream.
Writer io.Writer
}
Options configures color enablement. The flag bools come from the root command's persistent --no-color / --color flags; Writer is the destination the BARE helpers resolve their auto color against (typically stdout). The NO_COLOR / CLICOLOR_FORCE / TERM environment variables are consulted by Configure itself.
type Printer ¶
type Printer struct {
// contains filtered or unexported fields
}
Printer binds an io.Writer so call sites can emit styled lines without threading the writer through every helper. Each method writes ONE line (newline-terminated) and resolves color against the BOUND writer, so a Printer over stderr colors independently of stdout. Nil-safe: a zero Printer writes to os.Stdout.
type Styler ¶ added in v0.1.55
type Styler struct {
// contains filtered or unexported fields
}
Styler renders styled strings resolved against a SPECIFIC writer's color enablement. Use it (via For) at stderr call sites where the bare helpers — which resolve against stdout — would mis-decide (e.g. colored stderr while stdout is piped). The methods mirror the package-level helpers.
func (Styler) Success ¶ added in v0.1.55
Success renders a "✓ <str>" success line in green (glyph kept when disabled).
Source Files