output

Documentation

Overview

Package output is the CLI's single rendering entry point. Render takes a format and a value and writes it as human-styled text, newline-delimited JSON, or CSV. It is a deep module: callers decide the format and whether color is wanted, and the package hides lipgloss styling, per-entity layout, and the tolerant CSV/JSON encoding behind one call.

The package imports the spur response types it renders; spur stays a pure API client with no presentation dependency, so the direction is output → spur only.

Index

• func ColorEnabled(w io.Writer) bool
• func FormatList() string
• func HuhTheme(color bool) huh.Theme
• func HumanizeBytes(n int64) string
• func Infof(w io.Writer, color bool, format string, a ...any)
• func IsTerminal(w io.Writer) bool
• func Render(w io.Writer, format Format, color bool, v any) error
• func Successf(w io.Writer, color bool, format string, a ...any)
• func Warnf(w io.Writer, color bool, format string, a ...any)
• func Writer(w io.Writer, color bool) io.Writer
• type Format
  • func DefaultFormat(isTTY bool) Format
  • func ParseFormat(s string) (Format, error)
• type Styles
  • func NewStyles(w io.Writer, color bool) Styles

Functions

func ColorEnabled

func ColorEnabled(w io.Writer) bool

ColorEnabled reports whether w should receive ANSI color: an interactive terminal whose environment permits it. Detection honors the NO_COLOR convention (https://no-color.org), CLICOLOR=0, and CLICOLOR_FORCE, and returns no color for a pipe or file. The --no-color flag is applied by the caller on top of this.

func FormatList

func FormatList() string

FormatList is the pipe-joined list of valid formats, for flag help.

func HuhTheme

func HuhTheme(color bool) huh.Theme

HuhTheme is the form theme for interactive prompts (spur auth), derived from the same palette as the report renderer so the prompt and the output read as one product. huh detects the terminal background itself and passes isDark. When color is false the base theme is returned unchanged, which renders without color.

func HumanizeBytes

func HumanizeBytes(n int64) string

HumanizeBytes renders a byte count with a binary (IEC) unit suffix, so a multi-gigabyte feed reads as "1.2 GiB" rather than a wall of digits.

func Infof

func Infof(w io.Writer, color bool, format string, a ...any)

Infof writes a neutral notice line to w.

func IsTerminal

func IsTerminal(w io.Writer) bool

IsTerminal reports whether w is an interactive terminal. A plain io.Writer (a file, a buffer, a pipe) is not, so this drives both the default-format choice and color suppression.

func Render

func Render(w io.Writer, format Format, color bool, v any) error

Render writes v to w in the given format. color enables ANSI styling for the text format; the caller is responsible for deciding it (typically terminal && !--no-color) so Render never second-guesses a non-terminal write. color is ignored for JSON and CSV, which are always plain.

func Successf

func Successf(w io.Writer, color bool, format string, a ...any)

Successf writes a green-marked confirmation line to w.

func Warnf

func Warnf(w io.Writer, color bool, format string, a ...any)

Warnf writes a warning line to w, marked with the cautionary palette.

func Writer

func Writer(w io.Writer, color bool) io.Writer

Writer wraps w so that styled output is degraded to what the destination supports: full color passes through, a 256-color terminal gets downsampled codes, and color==false strips ANSI entirely. When the caller demands color on a writer with no detectable capability (tests writing to a buffer), TrueColor is assumed.

Types

type Format

type Format string

Format is a supported output encoding.

const (
	// FormatText is the human-readable, styled report shown at a terminal.
	FormatText Format = "text"
	// FormatJSON is newline-delimited JSON, the pipe-friendly default.
	FormatJSON Format = "json"
	// FormatCSV is a header row plus one record per rendered value.
	FormatCSV Format = "csv"
)

func DefaultFormat

func DefaultFormat(isTTY bool) Format

DefaultFormat is the format used when the user did not pass --format. A terminal gets the styled human report; anything piped or redirected gets machine-friendly JSON so existing pipelines keep working.

func ParseFormat

func ParseFormat(s string) (Format, error)

ParseFormat validates a --format flag value.

type Styles

type Styles struct {
	Title   lipgloss.Style // section/report header text
	Frame   lipgloss.Style // tree connectors (├ │ └)
	Block   lipgloss.Style // block name
	Key     lipgloss.Style // field label
	Value   lipgloss.Style // field value
	Empty   lipgloss.Style // placeholder for absent values
	Bool    lipgloss.Style // boolean values
	Num     lipgloss.Style // numeric values
	Success lipgloss.Style // affirmative status markers
	Warning lipgloss.Style // cautionary status markers
}

Styles is the palette for the text renderer.

In lipgloss v2 styles are not bound to a writer: they always render full ANSI, and Writer degrades that output to what the destination supports (including stripping it entirely). Always print rendered styles through Writer(w, color).

func NewStyles

func NewStyles(w io.Writer, color bool) Styles

NewStyles builds the style palette for output destined for w. w is used only to pick the light or dark color variants: when it is a color-enabled terminal its background is queried; otherwise the dark palette is assumed (nothing colored is shown there anyway).