output

Documentation

Overview

Package output provides utilities for formatting and outputting CLI command results.

Index

• func AgentModeError(cmd *cobra.Command, errorType, message string, hints []string) error
• func AlreadyPrinted(err error) error
• func ApplyJqFilter(content interface{}, expression string) ([]interface{}, error)
• func ColorizeJSON(data []byte) []byte
• func Error(cmd *cobra.Command, err error) error
• func InitAgentMode(cmd *cobra.Command)
• func IsAgentMode() bool
• func IsAlreadyPrinted(err error) bool
• func PrepareCallOpts(cmd *cobra.Command) ([]operations.Option, error)
• func ResetAgentMode()
• func Result(cmd *cobra.Command, res interface{}) error
• func ShouldColorize(colorFlag string) bool
• func ValidateGlobalServerIndex(cmd *cobra.Command, count int) error
• func ValidateGlobalServerName(cmd *cobra.Command, validNames map[string]string) error
• func WantsRawJSON(cmd *cobra.Command) bool

Functions

func AgentModeError

func AgentModeError(cmd *cobra.Command, errorType, message string, hints []string) error

AgentModeError outputs a structured agent-mode error and returns a non-nil error for exit code 1. Used for CLI-level errors (not API errors) such as blocking the interactive configure command.

Single-print contract: outputs structured JSON exactly once to stderr, then returns the error. Callers must NOT print the error again.

func AlreadyPrinted

func AlreadyPrinted(err error) error

AlreadyPrinted wraps err in a marker type so callers (specifically cmd/compass/main.go) can detect that the friendly error rendering has already happened and suppress the default `fmt.Fprintln(os.Stderr, err)`. Callers that don't recognize the wrapper still get a working error value: .Error() returns the underlying message and errors.Is/As both work via Unwrap.

func ApplyJqFilter

func ApplyJqFilter(content interface{}, expression string) ([]interface{}, error)

ApplyJqFilter applies a jq expression to the given content and returns the results. The content is first marshaled to JSON and back to ensure a clean interface{} structure, then the jq expression is evaluated against it.

func ColorizeJSON

func ColorizeJSON(data []byte) []byte

ColorizeJSON adds ANSI color codes to formatted JSON output. It distinguishes keys from string values, and highlights numbers, booleans, and null.

func Error

func Error(cmd *cobra.Command, err error) error

Error handles SDK errors, outputting structured JSON when --output-format=json, --jq, or agent mode is active. Always returns the error for non-zero exit code. For non-JSON output modes outside agent mode, returns the error as-is (with optional header output when --include-headers is set).

func InitAgentMode

func InitAgentMode(cmd *cobra.Command)

InitAgentMode detects and caches agent mode state for the lifetime of the process. In production, each CLI invocation is a separate process, so this is evaluated exactly once. For in-process test scenarios with multiple command executions, call ResetAgentMode() between runs to re-evaluate.

Checks --agent-mode flag first (explicit override), then auto-detects from well-known AI agent environment variables.

func IsAgentMode

func IsAgentMode() bool

IsAgentMode returns true when agent mode is active.

func IsAlreadyPrinted

func IsAlreadyPrinted(err error) bool

IsAlreadyPrinted reports whether err (or any error in its chain) was returned from output.Error() and has therefore already been rendered to the user. main.go uses this to skip the default error print so the message isn't duplicated.

func PrepareCallOpts

func PrepareCallOpts(cmd *cobra.Command) ([]operations.Option, error)

PrepareCallOpts builds common SDK call options from CLI flags. Parses --header flags into operations.WithSetHeaders options. Server resolution and skip-deserialization are handled per-operation.

func ResetAgentMode

func ResetAgentMode()

ResetAgentMode resets agent mode state for testing. This allows tests to re-evaluate agent mode detection on the next InitAgentMode call.

func Result

func Result(cmd *cobra.Command, res interface{}) error

Result formats and outputs the response based on the --output-format flag.

func ShouldColorize

func ShouldColorize(colorFlag string) bool

ShouldColorize determines whether output should include ANSI color codes. It checks agent mode, the --color flag value, NO_COLOR / FORCE_COLOR env vars, and TTY status.

func ValidateGlobalServerIndex

func ValidateGlobalServerIndex(cmd *cobra.Command, count int) error

ValidateGlobalServerIndex validates the --server flag as an integer index in range [0, count). Provides clear error messages for invalid values. The actual server application happens in client.NewClient via sdk.WithServerIndex (which handles server URL template variable resolution).

func ValidateGlobalServerName

func ValidateGlobalServerName(cmd *cobra.Command, validNames map[string]string) error

ValidateGlobalServerName validates the --server flag against a named server map. The actual server application happens in client.NewClient via sdk.WithServer.

func WantsRawJSON

func WantsRawJSON(cmd *cobra.Command) bool

WantsRawJSON returns true when the user has requested JSON output format (either --output-format=json or --jq is set), meaning the CLI should prefer raw JSON passthrough over typed-struct marshaling.