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.

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-exact parse; `ok=false` and `FormatText` for empty/unknown

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	Used by
`SuccessIcon` / `WarnIcon` / `FailIcon`	`string`	`Status` completion icons
`SuccessStyle` / `WarnStyle` / `FailStyle`	`lipgloss.Style`	completed-line style
`SpinnerStyle`	`lipgloss.Style`	spinner frames
`SpinnerFrames`	`[]string`	animation frames (empty → built-in dot)
`ProgressFilled` / `ProgressEmpty` / `ProgressHead`	`rune`	progress-bar glyphs (`ProgressHead` 0 → reuse `ProgressFilled`)

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