cmdutil

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ExitFailure   = 1
	ExitCancelled = 2
	ExitTimeout   = 124
)

Variables

This section is empty.

Functions

func AddJSONFieldsFlag 

func AddJSONFieldsFlag(cmd *cobra.Command, target *string)

AddJSONFieldsFlag adds a --json flag that accepts optional field specification

func AddListFlags 

func AddListFlags(cmd *cobra.Command, flags *ListFlags, defaultLimit int)

AddListFlags registers --limit, --json, --plain, and --no-header flags on a command.

func AddPlainFlags added in v0.8.3 

func AddPlainFlags(cmd *cobra.Command, flags *ListFlags)

AddPlainFlags registers --plain and --no-header flags on a command. Use this for list commands that already register --json separately.

func AddViewFlags 

func AddViewFlags(cmd *cobra.Command, opts *ViewOptions)

AddViewFlags adds --json and --web flags to a command.

func AliasAwareHelp added in v0.9.0 

func AliasAwareHelp(cmd *cobra.Command, canonical, alias string)

AliasAwareHelp makes help output reflect whichever alias the user typed.

func BuildResultError 

func BuildResultError(ctx context.Context, p *output.Printer, client api.ClientInterface, build *api.Build, showDetails bool) error

BuildResultError prints the final build result and returns an appropriate exit error. Used by both the standard watch and TUI watch paths.

func Confirm added in v0.10.0 

func Confirm(title string, value *bool) error

Confirm asks a yes/no question inline with left-aligned compact buttons.

func DeprecateCommand added in v0.9.0 

func DeprecateCommand(cmd *cobra.Command, new, removeVersion string)

DeprecateCommand marks a command as deprecated with a consistent message format.

func DeprecateFlag added in v0.9.0 

func DeprecateFlag(cmd *cobra.Command, old, new, removeVersion string)

DeprecateFlag marks a flag as deprecated with a consistent message format.

func FormatAgentStatus 

func FormatAgentStatus(a api.Agent) string

FormatAgentStatus returns a formatted status string for an agent.

func MarkExperimental added in v0.9.0 

func MarkExperimental(f *Factory, cmd *cobra.Command)

MarkExperimental tags a command as experimental and warns on each invocation.

func NotAuthenticatedError 

func NotAuthenticatedError(ctx context.Context, serverURL string, keyringErr error) *api.ValidationError

NotAuthenticatedError returns a not-authenticated error with a hint that covers all authentication methods.

func OpenURLOrWarn added in v0.10.0 

func OpenURLOrWarn(p *output.Printer, url string)

OpenURLOrWarn opens url in the browser, warning on failure. Never returns an error — safe to call after a mutation.

func ParseID 

func ParseID(s string, entity string) (int, error)

ParseID converts a string argument to an integer ID.

func PrintFailureSummary 

func PrintFailureSummary(ctx context.Context, p *output.Printer, client api.ClientInterface, buildID, buildNumber, webURL, statusText string)

func ProbeGuestAccess 

func ProbeGuestAccess(ctx context.Context, serverURL string) bool

ProbeGuestAccess checks whether the server at serverURL supports guest access; honors ctx for cancellation.

func Prompt added in v0.10.0 

func Prompt(field huh.Field) error

Prompt runs a single huh field with the CLI theme; does not echo — use PromptString / Select / Confirm for that.

func PromptOptionalString added in v0.10.0 

func PromptOptionalString(p *output.Printer, title, description string, value *string) error

PromptOptionalString asks for free-form text without rejecting empty input, useful when blank means "skip".

func PromptSecret added in v0.10.0 

func PromptSecret(title string, value *string) error

PromptSecret asks for a hidden value and never echoes it back.

func PromptString added in v0.10.0 

func PromptString(p *output.Printer, title, description string, value *string) error

PromptString asks for free-form text and echoes the answer back so it survives in scrollback.

func RequireNonEmpty added in v0.10.0 

func RequireNonEmpty(s string) error

RequireNonEmpty is a huh validator that rejects empty or whitespace-only input.

func ResolveAgent 

func ResolveAgent(client api.ClientInterface, nameOrID string) (*api.Agent, error)

ResolveAgent resolves an agent name or ID to an Agent object.

func ResolveAgentID 

func ResolveAgentID(client api.ClientInterface, nameOrID string) (int, string, error)

ResolveAgentID resolves an agent name or ID to a numeric agent ID and name.

func RunForm added in v1.0.0 

func RunForm(groups ...*huh.Group) error

RunForm runs a multi-group huh form with shift+tab navigation; use it instead of chaining Prompt calls so groups can navigate between each other.

func RunList 

func RunList(
	f *Factory,
	cmd *cobra.Command,
	flags *ListFlags,
	fieldSpec *api.FieldSpec,
	fetch func(client api.ClientInterface, fields []string) (*ListResult, error),
) error

RunList handles the shared boilerplate for list commands: limit validation, JSON field parsing, client creation, fetch, and output.

func Select added in v0.10.0 

func Select[T comparable](p *output.Printer, title string, options []huh.Option[T], value *T) error

Select presents a typed picker (filtering auto-enabled for 5+ options) and echoes the picked label back.

func SubcommandRequired 

func SubcommandRequired(cmd *cobra.Command, _ []string) error

SubcommandRequired is a RunE function for parent commands that require a subcommand.

func ValidateLimit 

func ValidateLimit(limit int) error

ValidateLimit returns an error if limit is not positive.

Types

type ExitError 

type ExitError struct {
	Code int
}

ExitError is returned by commands that need a specific exit code.

func (*ExitError) Error 

func (e *ExitError) Error() string

type Factory 

type Factory struct {
	// Global flags — set once by root command, read by subcommands.
	NoColor bool
	Quiet   bool
	Verbose bool
	NoInput bool

	// JSONOutput is set by commands that accept --json to signal that errors
	// should be emitted as structured JSON instead of human-readable text.
	JSONOutput bool

	// IOStreams provides standard I/O handles. Override in tests to capture output.
	IOStreams *IOStreams

	// Printer writes formatted output. Prefer this over the output package
	// free functions — it uses the Factory's IOStreams and respects Quiet/Verbose
	// without relying on package globals.
	Printer *output.Printer

	// ClientFunc returns an API client. Override in tests to inject mocks.
	ClientFunc func() (api.ClientInterface, error)

	// UpdateNotice is called after command execution to print update notices.
	UpdateNotice func()

	// Analytics is the FUS telemetry client; always nil-safe.
	Analytics *analytics.Client

	// StartTime captured at PersistentPreRun for duration_ms.
	StartTime time.Time
	// contains filtered or unexported fields
}

Factory provides shared dependencies to all commands. Instead of reaching for package-level globals, commands receive a Factory and use its methods/fields to get clients, check flags, etc.

func NewFactory 

func NewFactory() *Factory

NewFactory creates a Factory with production defaults.

func (*Factory) Client 

func (f *Factory) Client() (api.ClientInterface, error)

Client returns an API client using the configured ClientFunc.

func (*Factory) Context added in v0.10.0 

func (f *Factory) Context() context.Context

Context returns the Factory's root context; use this everywhere in our code rather than cmd.Context().

func (*Factory) HasLinkConfigFile added in v1.0.0 

func (f *Factory) HasLinkConfigFile() bool

HasLinkConfigFile reports whether any teamcity.toml exists in the cwd hierarchy without parsing it; safe to call from telemetry hooks because it never warns or triggers the once-gated load that HasLinkContext does.

func (*Factory) HasLinkContext added in v1.0.0 

func (f *Factory) HasLinkContext() bool

HasLinkContext reports whether a teamcity.toml in the cwd hierarchy matched the active server.

func (*Factory) InitOutput 

func (f *Factory) InitOutput()

InitOutput configures output settings from Factory flags. Called once after flags are parsed (in PersistentPreRun).

func (*Factory) IsInteractive 

func (f *Factory) IsInteractive() bool

IsInteractive returns true if the CLI can prompt the user.

func (*Factory) ResolveDefaultJob added in v0.10.0 

func (f *Factory) ResolveDefaultJob(explicit string) string

ResolveDefaultJob returns explicit, then TEAMCITY_JOB, then scope.Job, then a single Jobs entry.

func (*Factory) ResolveProject added in v0.10.0 

func (f *Factory) ResolveProject(explicit string) string

ResolveProject returns explicit, then TEAMCITY_PROJECT, then the linked scope's project.

func (*Factory) SetContext added in v0.10.0 

func (f *Factory) SetContext(ctx context.Context)

SetContext installs the signal-cancel root context; cmd.Execute keeps rootCmd's Cobra context in sync as a safety net.

func (*Factory) SkipLinkLookup added in v0.10.0 

func (f *Factory) SkipLinkLookup()

SkipLinkLookup pre-resolves this Factory's link to empty, isolating Resolve* from the host's teamcity.toml.

func (*Factory) WarnInsecureHTTP 

func (f *Factory) WarnInsecureHTTP(serverURL, credentialType string)

WarnInsecureHTTP prints a warning to stderr when connecting over plain HTTP.

type IOStreams 

type IOStreams struct {
	In     io.Reader
	Out    io.Writer
	ErrOut io.Writer
}

IOStreams provides the standard streams for commands to read/write. Commands should use these instead of os.Stdin/os.Stdout/os.Stderr directly, enabling tests to capture output without redirecting globals.

type JSONFieldsResult 

type JSONFieldsResult struct {
	Enabled bool
	Fields  []string
}

JSONFieldsResult represents the parsed result of --json flag

func ParseJSONFields 

func ParseJSONFields(cmd *cobra.Command, flagValue string, spec *api.FieldSpec, w io.Writer) (JSONFieldsResult, bool, error)

ParseJSONFields parses the --json flag value, returns (result, showHelp, error).

type ListFlags 

type ListFlags struct {
	Limit      int
	JSONFields string
	Plain      bool
	NoHeader   bool
}

ListFlags holds the common flags shared by all list commands.

type ListResult 

type ListResult struct {
	JSON     any
	Table    ListTable
	EmptyMsg string
	EmptyTip string
}

ListResult is returned by a list command's fetch function. Set either JSON (for JSON output) or Table (for table output). EmptyTip is shown alongside EmptyMsg when the table is empty.

type ListTable 

type ListTable struct {
	Headers  []string
	Rows     [][]string
	FlexCols []int
}

ListTable holds the data needed to print a table.

type ViewOptions 

type ViewOptions struct {
	JSON bool
	Web  bool
}

ViewOptions is shared by view commands that support JSON and web output.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.