Documentation
¶
Overview ¶
Package output is the single rendering, error, and exit-code authority for the CLI. Commands return errors and typed results through this package; nothing else writes to stdout/stderr or decides process exit codes.
Index ¶
Constants ¶
const ( // ExitOK means the command succeeded. ExitOK = 0 // ExitError means a generic failure. ExitError = 1 // ExitCancelled means the user or the environment cancelled the run. ExitCancelled = 2 // ExitNotFound means a requested resource does not exist. ExitNotFound = 3 // ExitAuth means authentication is required or failed. ExitAuth = 4 )
Process exit codes. These are a public contract for scripts and agents.
Variables ¶
This section is empty.
Functions ¶
func RenderError ¶
RenderError writes err to w — as a one-line JSON envelope {"error":{"code":"...","message":"...","hint":"..."}} when jsonMode is true, otherwise as human-readable "error: ..." / "hint: ..." lines — and returns the process exit code for the error. It must be called exactly once per failed invocation.
func RenderFields ¶
RenderFields writes label/value rows as two aligned columns — labels padded to the widest label, a two-space gutter, values verbatim with no trailing padding. It is the human layout for `show` commands.
func RenderTable ¶
RenderTable writes headers and rows as plain aligned columns: each column is padded to its widest cell, columns are separated by a two-space gutter, and the last cell of each line carries no trailing padding. No color, no external dependencies.
Types ¶
type CodedError ¶
CodedError is an error carrying a process exit code, a machine-readable error code for the JSON envelope, and an optional remediation hint.
func AuthError ¶
func AuthError(msg, hint string) *CodedError
AuthError returns a CodedError for missing or failed authentication (exit 4).
func CancelledError ¶
func CancelledError(msg string) *CodedError
CancelledError returns a CodedError for a cancelled run (exit 2).
func ErrorWithHint ¶
func ErrorWithHint(msg, hint string) *CodedError
ErrorWithHint returns a generic CodedError (exit 1) carrying a remediation hint for the envelope/human output.
func Errorf ¶
func Errorf(format string, a ...any) *CodedError
Errorf returns a generic CodedError (exit 1) with a formatted message.
func NotFoundError ¶
func NotFoundError(msg, hint string) *CodedError
NotFoundError returns a CodedError for a missing resource (exit 3).
func (*CodedError) Error ¶
func (e *CodedError) Error() string
Error implements the error interface.
type Mode ¶
type Mode struct {
// TTY is true when stdout is a terminal.
TTY bool
// CI is true when running under a CI system (CI or GITHUB_ACTIONS set).
CI bool
// Agent identifies a detected coding agent ("claude-code", "gemini-cli",
// "cursor") or is empty when none is detected.
Agent string
// Color is true when ANSI color output is appropriate.
Color bool
// JSON is true when the user requested machine-readable JSON output.
JSON bool
}
Mode describes the execution environment and the resulting rendering preferences for a single CLI invocation.
func DetectMode ¶
DetectMode inspects flags and the environment and returns the output Mode for this invocation.
func (Mode) Interactive ¶
Interactive reports whether it is appropriate to prompt the user: stdout is a TTY and we are not running under CI or a coding agent.
type Printer ¶
type Printer struct {
Out io.Writer
Err io.Writer
Mode Mode
// Quiet suppresses Status lines (--quiet); data on Out is never affected.
Quiet bool
}
Printer is the single writer for command output. Data goes to Out (stdout), progress goes to Err (stderr) so that piped/JSON consumers see clean data.
func (*Printer) EmitJSONLine ¶
EmitJSONLine writes v as one compact JSON line to Out — the NDJSON building block for streaming commands (e.g. `login --json`).
Source Files