output

Documentation

Overview

Package output renders command results either as a styled table/summary for humans or as indented JSON for machines (--json).

Index

• Variables
• func Emit(w io.Writer, asYAML bool, v any) error
• func Errorf(w io.Writer, format string, a ...any)
• func Hintf(w io.Writer, format string, a ...any)
• func HumanBlankLine(w io.Writer) error
• func Infof(w io.Writer, format string, a ...any)
• func JSON(w io.Writer, v any) error
• func KeyValues(w io.Writer, pairs [][2]string) error
• func Notef(w io.Writer, format string, a ...any)
• func PlainField(s string) string
• func PlainRow(w io.Writer, fields ...string) error
• func Progressf(w io.Writer, format string, a ...any)
• func SanitizeField(s string) string
• func Successf(w io.Writer, format string, a ...any)
• func Table(w io.Writer, headers []string, rows [][]string) error
• func Title(w io.Writer, s string)
• func ValidateJQ() error
• func Warnf(w io.Writer, format string, a ...any)
• func YAML(w io.Writer, v any) error
• type Streamer
  • func NewStreamer(w io.Writer, asYAML bool) Streamer

Variables

var (
	// Quiet suppresses incidental success/info lines (-q/--quiet).
	Quiet bool
	// Plain renders tables as tab-separated, unstyled rows (--plain).
	Plain bool
	// Interactive is true when stdout is a terminal. When false (piped or
	// redirected), Table drops its box-drawing frame so the rows stay
	// grep/awk-friendly, mirroring how color is stripped for non-TTY output.
	Interactive bool
)

Output mode toggles set from global flags before commands run.

var JQ string

JQ is the --jq filter applied to machine-readable output. Empty disables it.

It exists so a container image that ships only `ofga` can still extract a field — the common `fga store create | jq -r .store.id` idiom otherwise forces jq into every image, or two init containers (openfga/cli#395). `gh --jq` sets the precedent for the flag name and behaviour.

Functions

func Emit

func Emit(w io.Writer, asYAML bool, v any) error

Emit writes v as YAML when asYAML is set, otherwise as JSON. Commands that support --json also support the parallel --output yaml (or -o yaml) via this helper, so the two structured formats never need separate branches.

func Errorf

func Errorf(w io.Writer, format string, a ...any)

Errorf prints an error line with a red dot. Unlike Successf/Infof it is never suppressed by Quiet — errors must always reach the user.

func Hintf

func Hintf(w io.Writer, format string, a ...any)

Hintf writes a faint, indented follow-up line (e.g. a "try this next" hint after an error). Rendered on stderr by callers; not suppressed by --quiet so remediation guidance always shows.

func HumanBlankLine

func HumanBlankLine(w io.Writer) error

HumanBlankLine preserves a visual separator in human output without introducing an empty record in --plain output.

func Infof

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

Infof prints a muted informational line with a primary-colored dot (suppressed in Quiet/Plain).

func JSON

func JSON(w io.Writer, v any) error

JSON writes v as indented JSON to w. A typed nil slice (e.g. `var x []T` with zero rows) marshals to `null`, which breaks scripts doing `… --json | jq '.[]'` or length checks on empty result sets, so it is coerced to an empty slice and serialized as [].

func KeyValues

func KeyValues(w io.Writer, pairs [][2]string) error

KeyValues renders an aligned key/value block (used for "get" style output).

func Notef

func Notef(w io.Writer, format string, a ...any)

Notef prints a neutral, faint note line with a faint dot (suppressed in Quiet/Plain).

func PlainField

func PlainField(s string) string

PlainField makes one value safe to embed in a tab-separated, newline-delimited plain-output record without changing structured JSON or YAML data.

func PlainRow

func PlainRow(w io.Writer, fields ...string) error

PlainRow writes one unstyled, tab-separated record, matching the rows Table emits in Plain mode. Fields are sanitized so a tab or newline in server data cannot forge extra columns or records.

func Progressf

func Progressf(w io.Writer, format string, a ...any)

Progressf prints transient progress only for an interactive human session, keeping redirected and machine-readable command output quiet.

func SanitizeField

func SanitizeField(s string) string

SanitizeField removes terminal control characters from untrusted values before they are embedded in human-readable output. Structured output must keep the original data, so callers apply this only at terminal render sites.

func Successf

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

Successf prints a success line with a green dot (suppressed in Quiet/Plain).

func Table

func Table(w io.Writer, headers []string, rows [][]string) error

Table renders a simple, aligned table with a styled header. Columns are sized to their widest cell. It is intentionally dependency-light so it can be used from any command. In Plain mode it emits tab-separated, unstyled rows for grep/awk pipelines.

func Title

func Title(w io.Writer, s string)

Title prints a bold violet title line.

func ValidateJQ

func ValidateJQ() error

ValidateJQ reports whether the active filter parses, without running it.

func Warnf

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

Warnf prints a warning line with an amber dot (suppressed in Quiet/Plain).

func YAML

func YAML(w io.Writer, v any) error

YAML writes v as YAML to w. v is round-tripped through JSON first so field names and shapes match --json exactly (Go struct field names, json tags, and the same nil-slice-to-[] coercion as JSON), rather than diverging to yaml.v3's own default field-naming rules.

Types

type Streamer

type Streamer interface {
	Write(v any) error
	Close() error
}

Streamer emits a sequence of values incrementally, so a command that reads an unbounded result set does not have to hold all of it in memory before writing anything. The rendered output is byte-for-byte what Emit would have produced for the equivalent slice, so switching a command to streaming is not a change in its machine output.

Write may be called any number of times, including zero; Close must be called exactly once and its error must not be discarded, since it writes the closing delimiter.

func NewStreamer

func NewStreamer(w io.Writer, asYAML bool) Streamer

NewStreamer returns a Streamer matching Emit's choice of format.

Under --jq the values are buffered instead of streamed: a filter like `length` or `sort_by(.x)` has to see the whole document, so there is nothing to stream. That trades the memory bound for correctness, and only for invocations that opted into a filter.