output

package
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package output centralizes everything the CLI writes to a terminal and the process exit codes it uses. It is the only package (besides cmd/) allowed to call fmt.Print* — the `forbidigo` linter enforces that, so output formatting and exit codes stay in one place.

Exit codes (PLAN.md "Output and UX conventions"):

0 ok · 1 error · 2 usage · 3 auth required · 4 not found · 5 throttled

Index

Constants

View Source
const (
	CodeOK        = 0
	CodeError     = 1
	CodeUsage     = 2
	CodeAuth      = 3
	CodeNotFound  = 4
	CodeThrottled = 5
)

Exit codes. They are part of the CLI contract and are documented in docs/commands and the README.

Variables

This section is empty.

Functions

func ApplyJQ

func ApplyJQ(w io.Writer, expr string, data []byte) error

ApplyJQ runs a jq expression over JSON-encoded data and writes the results to out, one per line: a string result prints unquoted (which is what a script wants) and anything else prints as compact JSON. It implements the --jq flag, which is documented in PLAN.md's output conventions next to --json.

func Authf

func Authf(format string, args ...any) error

Authf builds an authentication-required error (exit 3).

func CodeOf

func CodeOf(err error) int

CodeOf returns the exit code for err: 0 for nil, the code carried by an *Error, the value from ExitCode for anything implementing ExitCoder, and 1 for anything else.

func DetectInteractive

func DetectInteractive(stdin io.Reader, stdout io.Writer, noInput bool) bool

DetectInteractive decides whether prompts are allowed: both stdin and stdout must be terminals, --no-input must be off and CI must not be set. PLAN.md requires the automatic detection; it is our logic, not cobra's or MSAL's, so it is tested on its own.

func Errorf

func Errorf(format string, args ...any) error

Errorf builds a generic (exit 1) error.

func HintOf

func HintOf(err error) string

HintOf returns the hint attached to err, if any: our own Error first, then any error implementing Hinter.

func HumanAge

func HumanAge(now, t time.Time) string

HumanAge renders how long ago t was, at a granularity that is useful at a glance. Future timestamps read as "in …", which matters for token expiry.

func HumanDuration

func HumanDuration(d time.Duration) string

HumanDuration renders a duration as the largest one or two units.

func HumanDurationSeconds

func HumanDurationSeconds(d time.Duration) string

HumanDurationSeconds renders a duration with a unit, for documented windows such as the 15-minute device-code sign-in window.

func IsTerminal

func IsTerminal(w io.Writer) bool

IsTerminal reports whether w is an interactive terminal.

func JoinNonEmpty

func JoinNonEmpty(sep string, parts ...string) string

JoinNonEmpty joins the non-empty strings with sep; a small helper that keeps renderers from emitting stray separators for missing values.

func NotFoundf

func NotFoundf(format string, args ...any) error

NotFoundf builds a not-found error (exit 4).

func Throttledf

func Throttledf(format string, args ...any) error

Throttledf builds a throttled error (exit 5).

func Usagef

func Usagef(format string, args ...any) error

Usagef builds a usage error (exit 2).

func WithCode

func WithCode(err error, code int) error

WithCode forces an exit code onto an existing error, preserving its text.

func WithHint

func WithHint(err error, hint string) error

WithHint attaches a copy of err that carries a suggested fix. The hint is printed under the error, never mixed into the message, so scripts that parse the message stay stable. The exit code of the original error is preserved.

Types

type Error

type Error struct {
	Code int
	Msg  string
	Hint string
	Err  error
}

Error is an error that carries the process exit code and, optionally, the one-line fix we want to show the user.

func (*Error) Error

func (e *Error) Error() string

Error implements error.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap exposes the wrapped cause.

type ExitCoder

type ExitCoder interface {
	ExitCode() int
}

ExitCoder is implemented by errors that know their own exit code, such as the Graph APIError (a 404 is exit 4, a 429 is exit 5, and so on).

type Hinter

type Hinter interface {
	Hint() string
}

Hinter is implemented by errors that carry a suggested fix.

type Options

type Options struct {
	Out  io.Writer
	Err  io.Writer
	JSON bool
	// JQ is a jq expression applied to the JSON output. Setting it implies
	// JSON mode, so --jq alone is enough.
	JQ          string
	NoColor     bool
	Quiet       bool
	Verbose     int
	Interactive bool
}

Options configures a Printer. The CLI fills it from global flags plus TTY detection; tests construct it directly.

type Printer

type Printer struct {
	// contains filtered or unexported fields
}

Printer writes everything the CLI shows a human, in the one place the linters allow formatted output. It never writes to os.Stdout or os.Stderr directly.

func New

func New(opts Options) *Printer

New builds a Printer. Colour is on only for a terminal that did not ask for plain text: NO_COLOR, TERM=dumb, --no-color, --json and a pipe all disable it. CLICOLOR_FORCE=1 keeps colour even when the output is not a terminal, which is what the pty-based tests and colour-sensitive scripts use.

func (*Printer) Bold

func (p *Printer) Bold(s string) string

Bold renders s bold on a terminal and unchanged otherwise, so a caller does not have to know whether styling is on.

func (*Printer) Color

func (p *Printer) Color() bool

Color reports whether styled output is enabled.

func (*Printer) Debugf

func (p *Printer) Debugf(format string, args ...any)

Debugf writes diagnostics to stderr when -v/--verbose is set.

func (*Printer) Definitions

func (p *Printer) Definitions(pairs [][2]string)

Definitions prints aligned label/value pairs, the shape used by `teams auth status`, `teams doctor` and `teams cache info`.

func (*Printer) Dim

func (p *Printer) Dim(s string) string

Dim renders s faint on a terminal and unchanged otherwise.

func (*Printer) Err

func (p *Printer) Err() io.Writer

Err returns the stderr stream.

func (*Printer) Errorf

func (p *Printer) Errorf(format string, args ...any)

Errorf writes an error to stderr without exiting; use the returned error to carry the exit code.

func (*Printer) Interactive

func (p *Printer) Interactive() bool

Interactive reports whether the CLI may prompt: a TTY on both ends and no --no-input or CI environment. PLAN.md: non-interactive mode never prompts, it fails fast with an exit code.

func (*Printer) JQ

func (p *Printer) JQ() string

JQ returns the --jq expression, or "".

func (*Printer) JSON

func (p *Printer) JSON(v any) error

JSON encodes v to stdout with a stable two-space indent. It is the only output path that is a documented schema, so it never contains styling.

func (*Printer) JSONBytes

func (p *Printer) JSONBytes(raw []byte) error

JSONBytes writes an already-encoded JSON document, re-indented, through the same --jq path JSON uses.

It is the printer for `teams api`, where the response is a document the CLI did not build and does not model: printing it as a Go value would mean decoding and re-encoding something whose schema is whatever Graph returned. A body that is not JSON at all is not accepted here (the caller writes it verbatim instead).

func (*Printer) JSONMode

func (p *Printer) JSONMode() bool

JSONMode reports whether --json or --jq was requested.

func (*Printer) Markdown

func (p *Printer) Markdown(s, indent string)

Markdown renders a message body or a description for a human. On a terminal the markdown is styled through glamour; when the output is piped it is printed verbatim, because markdown is already plain text and a script wants the source, not a styled version of it (PLAN.md "Output and UX conventions").

indent is prefixed to every rendered line, which is how a body reads as part of the header line above it.

func (*Printer) Out

func (p *Printer) Out() io.Writer

Out returns the stdout stream, for commands that stream (file download).

func (*Printer) Print

func (p *Printer) Print(args ...any)

Print writes to stdout without a trailing newline.

func (*Printer) Printf

func (p *Printer) Printf(format string, args ...any)

Printf writes formatted output to stdout.

func (*Printer) Println

func (p *Printer) Println(args ...any)

Println writes a line to stdout.

func (*Printer) Quiet

func (p *Printer) Quiet() bool

Quiet reports whether --quiet was requested.

func (*Printer) ReportError

func (p *Printer) ReportError(err error)

ReportError prints an error and its hint exactly once, in the shape users and scripts expect: `error: …` on stderr, then an indented `hint: …`.

func (*Printer) Statusf

func (p *Printer) Statusf(format string, args ...any)

Statusf writes progress to stderr, so stdout stays parseable. It is suppressed by --quiet.

func (*Printer) Successf

func (p *Printer) Successf(format string, args ...any)

Successf prints a short confirmation with a green check on a TTY.

func (*Printer) Table

func (p *Printer) Table(headers []string, rows [][]string)

Table renders a table to stdout: a bordered, styled table on a terminal and tab-separated plain text when piped, so scripts get a stable format without having to strip ANSI escapes.

func (*Printer) Warnf

func (p *Printer) Warnf(format string, args ...any)

Warnf writes a warning to stderr.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL