Formats & options reference¶

A concise, information-oriented reference for the whole surface. The authoritative per-symbol API — signatures, doc comments, runnable examples — lives on pkg.go.dev; this page is the at-a-glance map.

The rest of the reference tier answers the questions this page does not:

Behaviour by format — what each method does in each format, which options are ignored where, and the layout, quoting and truncation rules.
Errors and failure modes — every error message, what causes it, what panics, and what fails silently.
What this does not do — the boundaries, and the workaround for each.

Formats¶

`Format`	Value	`Write` behaviour	`Table` behaviour
`FormatText`	`text`	calls your `textFunc`	aligned, truncated text table
`FormatJSON`	`json`	indented JSON of `data`	indented JSON of rows
`FormatYAML`	`yaml`	YAML of `data`	YAML of rows
`FormatCSV`	`csv`	tabulate `data`	comma-delimited, header row
`FormatTSV`	`tsv`	tabulate `data`	tab-delimited, header row
`FormatMarkdown`	`markdown`	tabulate `data`	GFM table (pipe/newline-safe)

Helpers:

Symbol	Purpose
`Formats() []Format`	canonical value set, stable order — use for a flag's allowed values
`ParseFormat(s) (Format, bool)`	case-insensitive parse; returns `(FormatText, false)` for empty/unknown

Formats() order is text, json, yaml, csv, tsv, markdown. ParseFormat lower-cases its input before matching, so JSON and json are the same value. It never returns an error: an unrecognised string yields text output, and the only way to detect the typo is the second return value.

Constructing a Renderer¶

output.New(opts ...Option) *Renderer

Option	Default	Effect
`WithWriter(io.Writer)`	`os.Stderr`	destination for all output
`WithFormat(Format)`	`FormatText`	the output format
`WithInteractive(bool)`	auto (`IsInteractive()`)	force animate / plain
`WithTheme(Theme)`	`DefaultTheme()`	icons, styles, spinner, bar

IsInteractive() bool — the default detector: TTY on stdout and CI != "true".

Renderer methods¶

Method	Notes
`Write(data any, textFunc func(io.Writer)) error`	format-aware; `textFunc` may be nil for non-text formats
`Table(rows any, opts ...TableOption) error`	slice of structs (tags) or maps (`WithColumns`)
`Render(markdown string) error`	Markdown → styled ANSI (glamour); no-op in JSON mode
`Emit(Response) error`	JSON envelope; no-op unless format is JSON
`EmitError(command string, err error) error`	error envelope, via `Emit`
`IsJSON() bool` / `Format() Format`	inspect configuration
`Status() *Status`	live multi-step status display
`Progress(total int, description string) *Progress`	known-total bar
`Spin(ctx, msg, fn) error`	spinner around indeterminate work

SpinWithResult[T any](r *Renderer, ctx, msg, fn) (T, error) — spinner that returns a value (a free function because Go methods cannot add a type parameter).

Response envelope¶

type Response struct {
    Status  string `json:"status"`            // StatusSuccess | StatusError | StatusWarning
    Command string `json:"command"`
    Data    any    `json:"data,omitempty"`
    Error   string `json:"error,omitempty"`
}

Table options¶

`TableOption`	Effect
`WithColumns(cols ...Column)`	explicit columns (required for maps)
`WithSortBy(header string)`	sort by a `Sortable` column (numeric-aware)
`WithSortDescending()`	reverse the sort
`WithNoHeader()`	omit the header row
`WithNoTruncation()`	do not truncate to terminal width
`WithMaxWidth(int)`	override terminal-width detection

Column{Header, Field, Width, Sortable, Formatter} — Field is the struct field name or map key; Formatter func(any) string overrides cell rendering. Struct tag form: `table:"Header,sortable"` (- excludes the field).

Theme¶

DefaultTheme() Theme — check/warn/cross icons, magenta braille spinner, ASCII bar.

Field	Type	Default	Used by
`SuccessIcon`	`string`	`✓`	`Status.Success`
`WarnIcon`	`string`	`⚠`	`Status.Warn`
`FailIcon`	`string`	`✗`	`Status.Fail`
`SuccessStyle`	`lipgloss.Style`	256-colour `42` (green)	the finalised success line
`WarnStyle`	`lipgloss.Style`	256-colour `214` (amber)	the finalised warning line
`FailStyle`	`lipgloss.Style`	256-colour `196` (red)	the finalised failure line
`SpinnerStyle`	`lipgloss.Style`	256-colour `205` (magenta)	`Spin` frames, `Status.Update` icon
`SpinnerFrames`	`[]string`	`⣾ ⣽ ⣻ ⢿ ⡿ ⣟ ⣯ ⣷`	`Spin`, `Status.Update`
`ProgressFilled`	`rune`	`=`	filled cells of the bar
`ProgressEmpty`	`rune`	a space	empty cells of the bar
`ProgressHead`	`rune`	`>`	the leading cell of a partial bar

Zero-value behaviour:

ProgressHead == 0 reuses ProgressFilled for the leading cell.
An empty SpinnerFrames makes Spin fall back to the built-in bubbles dot spinner, but makes Status.Update render a single space as its icon. The two are not consistent — see theming.

The theme controls only the progress family (Status, Progress, Spin). It has no effect on Table, Write, Emit or Render.

Styling is not conditional on interactivity: a renderer built with WithInteractive(false) still emits ANSI colour from these styles, and NO_COLOR / TERM=dumb are not consulted. To suppress colour, supply a theme whose styles are bare lipgloss.NewStyle() values.

Subpackage: `output/cobra`¶

Import gitlab.com/phpboyscout/go/output/cobra (conventionally aliased ocobra). The only part of the toolkit that depends on cobra.

Symbol	Purpose
`OutputFlag` (const `"output"`)	the flag name read and defined
`RegisterOutputFlag(cmd)`	define `--output` (default `text`, all formats)
`Format(cmd) output.Format`	read `--output` (default `FormatText`)
`IsJSONOutput(cmd) bool`	is `--output json`?
`NewRenderer(cmd, opts...) *output.Renderer`	writer = `cmd.OutOrStdout()`, format = `--output`
`Emit(cmd, resp)` / `EmitError(cmd, command, err)`	envelope sugar