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 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 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 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 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.