output

Documentation

Overview

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

Package output — incremental item output for pagination and streaming. This file is generated when at least one operation uses pagination or streaming.

Package output — pagination support. This file is generated only when at least one operation has pagination.

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 GenericFromRawBody(res interface{}) (interface{}, bool)
• func HasMorePages(res interface{}) bool
• func InitAgentMode(cmd *cobra.Command)
• func IsAgentMode() bool
• func IsDisplayed(err error) bool
• func IsResponseDecodeError(err error) bool
• func PaginatedResult(cmd *cobra.Command, res interface{}, contentFieldName, resultsFieldName string, ...) error
• 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 ValidateOutputFormat(cmd *cobra.Command) 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 GenericFromRawBody

func GenericFromRawBody(res interface{}) (interface{}, bool)

GenericFromRawBody reads a skip-deserialization response's raw body and decodes it into generic types (map/slice/scalar), which never fails on schema drift. Returns (value, true) on success. Pass the result to Result for a lenient fallback when a strict typed decode fails on server data that drifted from the spec. The generic value carries the same JSON shape the typed path would emit.

func HasMorePages

func HasMorePages(res interface{}) bool

HasMorePages reports whether a paginated response indicates further pages. It reads the response body's own hasMore flag (Object.HasMore) rather than the Next closure, which the generated SDK always assigns non-nil regardless of whether more pages exist. Returns false when the body was not deserialized (raw-JSON or --dry-run). Does not make any API calls.

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 IsDisplayed

func IsDisplayed(err error) bool

IsDisplayed reports whether err was already surfaced to the user by Error.

func IsResponseDecodeError

func IsResponseDecodeError(err error) bool

IsResponseDecodeError reports whether err came from decoding a server response whose shape did not match the expected schema (e.g. a numeric field arriving as a string). Exported so commands can fall back to lenient generic output.

func PaginatedResult

func PaginatedResult(cmd *cobra.Command, res interface{}, contentFieldName, resultsFieldName string, maxPages int) error

PaginatedResult streams all pages from a paginated response, outputting items incrementally. contentFieldName is the Go field name of the content on the response envelope (e.g., "Res"). resultsFieldName is the Go field path of the items slice on the content type (e.g., "ResultArray" or "PageInfo.ResultArray"). When resultsFieldName is empty (cursor/URL pagination without explicit results), the entire content object is output per page. maxPages limits pagination depth (0 = unlimited).

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 ValidateOutputFormat

func ValidateOutputFormat(cmd *cobra.Command) error

ValidateOutputFormat rejects formats that are recognized but not currently supported, so the CLI errors clearly instead of silently falling back to pretty. Shares resolveOutputFormat's precedence so it also catches a format set via config. ("table" is deliberately disabled: Speakeasy's formatter is scalar-only by design, so it hides the primary result array on list endpoints.)

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.