cobra

Documentation

Overview

Package cobra defines the supported Cobra runtime boundary for generated CLIs.

Index

• func AddGeneratedCommands(rootCmd *spcobra.Command, client *Client, specs []CommandSpec, ...) error
• func CheckError(resp *http.Response) error
• func ConfirmPrompt(message string) bool
• func ExtractField(data map[string]interface{}, field string) string
• func ExtractRows(data map[string]interface{}, columns []string) [][]string
• func FetchAllPages(client *Client, method, path string, baseQuery url.Values) ([]interface{}, error)
• func FormatValue(v interface{}) string
• func GetTerminalWidth() int
• func IsStdinTTY() bool
• func IsTTY() bool
• func PrintDetail(w io.Writer, fields map[string]interface{})
• func PrintJSON(w io.Writer, data interface{}) error
• func PrintTable(w io.Writer, columns []string, rows [][]string)
• func ReadBody(resp *http.Response) ([]byte, error)
• type APIError
  • func (e *APIError) Error() string
• type ArgBinding
• type Client
  • func NewClient(baseURL, apiKey, token string) *Client
  • func (c *Client) Do(method, path string, query url.Values, body any) (*http.Response, error)
• type CommandGroup
• type CommandSpec
• type Field
• type OutputFormat
• type OutputSpec
• type PaginatedResponse
• type PaginationSpec
• type Param
• type RequestBodySpec
• type RuntimeOptions

Functions

func AddGeneratedCommands

func AddGeneratedCommands(rootCmd *spcobra.Command, client *Client, specs []CommandSpec, opts RuntimeOptions) error

AddGeneratedCommands builds Cobra commands from generated command specs.

func CheckError

func CheckError(resp *http.Response) error

CheckError returns a structured error for non-2xx responses.

func ConfirmPrompt

func ConfirmPrompt(message string) bool

ConfirmPrompt asks the user for confirmation.

func ExtractField

func ExtractField(data map[string]interface{}, field string) string

ExtractField extracts a field from a generic map.

func ExtractRows

func ExtractRows(data map[string]interface{}, columns []string) [][]string

ExtractRows extracts table rows from a paginated response.

func FetchAllPages

func FetchAllPages(client *Client, method, path string, baseQuery url.Values) ([]interface{}, error)

FetchAllPages follows next_page_token until the resource is exhausted.

func FormatValue

func FormatValue(v interface{}) string

FormatValue formats a value for human-readable CLI display.

func GetTerminalWidth

func GetTerminalWidth() int

GetTerminalWidth returns the terminal width or a default.

func IsStdinTTY

func IsStdinTTY() bool

IsStdinTTY returns true if stdin is a terminal.

func IsTTY

func IsTTY() bool

IsTTY returns true if stdout is a terminal.

func PrintDetail

func PrintDetail(w io.Writer, fields map[string]interface{})

PrintDetail prints a single resource as key-value pairs.

func PrintJSON

func PrintJSON(w io.Writer, data interface{}) error

PrintJSON outputs data as formatted JSON.

func PrintTable

func PrintTable(w io.Writer, columns []string, rows [][]string)

PrintTable renders tabular data to stdout using a simple columnar layout.

func ReadBody

func ReadBody(resp *http.Response) ([]byte, error)

ReadBody reads and closes an HTTP response body.

Types

type APIError

type APIError struct {
	HTTPStatus int
	Code       int    `json:"code"`
	Message    string `json:"message"`
}

APIError is a structured API failure returned by CheckError.

func (*APIError) Error

func (e *APIError) Error() string

type ArgBinding

type ArgBinding struct {
	Source      string `json:"source"`
	Name        string `json:"name"`
	DisplayName string `json:"display_name,omitempty"`
}

ArgBinding binds a positional argument to a request source field.

type Client

type Client struct {
	BaseURL    string
	APIKey     string
	Token      string
	HTTPClient *http.Client
	Debug      bool
	TraceHTTP  bool
	LogFormat  string
	LogFile    string
}

Client is the shared HTTP client used by the generated Cobra runtime.

func NewClient

func NewClient(baseURL, apiKey, token string) *Client

NewClient constructs a runtime HTTP client with sane defaults.

func (*Client) Do

func (c *Client) Do(method, path string, query url.Values, body any) (*http.Response, error)

Do issues an authenticated HTTP request against the generated API surface.

type CommandGroup

type CommandGroup struct {
	ID    string
	Title string
}

CommandGroup configures a top-level Cobra group for generated commands.

type CommandSpec

type CommandSpec struct {
	OperationID string           `json:"operation_id"`
	Method      string           `json:"method"`
	Path        string           `json:"path"`
	Summary     string           `json:"summary"`
	Description string           `json:"description,omitempty"`
	Tags        []string         `json:"tags,omitempty"`
	Parameters  []Param          `json:"parameters,omitempty"`
	RequestBody *RequestBodySpec `json:"request_body,omitempty"`
	Command     []string         `json:"command,omitempty"`
	Args        []ArgBinding     `json:"args,omitempty"`
	Confirm     string           `json:"confirm,omitempty"`
	Output      OutputSpec       `json:"output,omitempty"`
	Pagination  *PaginationSpec  `json:"pagination,omitempty"`
}

CommandSpec is generated CLI metadata for one API operation.

type Field

type Field struct {
	Name        string   `json:"name"`
	Type        string   `json:"type"`
	Description string   `json:"description,omitempty"`
	Required    bool     `json:"required,omitempty"`
	Enum        []string `json:"enum,omitempty"`
}

Field describes one generated JSON request body field.

type OutputFormat

type OutputFormat string

OutputFormat represents the output format shared by generated Cobra commands.

const (
	// OutputText renders human-friendly output such as tables and details.
	OutputText OutputFormat = "text"
	// OutputJSON renders machine-readable JSON output.
	OutputJSON OutputFormat = "json"
)

type OutputSpec

type OutputSpec struct {
	Mode         string   `json:"mode,omitempty"`
	TableColumns []string `json:"table_columns,omitempty"`
	QuietFields  []string `json:"quiet_fields,omitempty"`
}

OutputSpec declares how a response should be rendered.

type PaginatedResponse

type PaginatedResponse struct {
	Data          []interface{} `json:"data"`
	NextPageToken string        `json:"next_page_token"`
}

PaginatedResponse is the minimal envelope used by FetchAllPages.

type PaginationSpec

type PaginationSpec struct {
	ItemsField         string `json:"items_field,omitempty"`
	NextPageTokenField string `json:"next_page_token_field,omitempty"`
}

PaginationSpec describes a paginated collection envelope.

type Param

type Param struct {
	Name        string   `json:"name"`
	In          string   `json:"in"`
	Type        string   `json:"type"`
	Description string   `json:"description,omitempty"`
	Required    bool     `json:"required,omitempty"`
	Enum        []string `json:"enum,omitempty"`
}

Param describes one generated endpoint parameter.

type RequestBodySpec

type RequestBodySpec struct {
	Required    bool    `json:"required,omitempty"`
	ContentType string  `json:"content_type,omitempty"`
	SchemaType  string  `json:"schema_type,omitempty"`
	InputMode   string  `json:"input_mode,omitempty"`
	Fields      []Field `json:"fields,omitempty"`
}

RequestBodySpec describes generated request body input behavior.

type RuntimeOptions

type RuntimeOptions struct {
	RunOverrides             map[string]func(*Client) func(*spcobra.Command, []string) error
	CommandMutators          map[string]func(*spcobra.Command)
	ResponseRenderers        map[string]func(*spcobra.Command, []byte) error
	RootGroupResolver        func(commandPath []string) *CommandGroup
	GroupDescriptionResolver func(commandPath []string) string
}

RuntimeOptions customizes generated Cobra command construction.