cmdutil

func APIErr ¶

func APIErr(err error, subject, notFoundCode, notFoundMsg string, notFoundSuggestions ...string) *clierrors.CLIError

APIErr converts an apiclient error into a structured CLIError.

notFoundCode and notFoundMsg customise the 404 case for the calling resource (e.g. "run.not_found", "No run found for %q"). notFoundMsg is passed through fmt.Sprintf with subject as the single argument.

Optional notFoundSuggestions are appended to the 404 error (useful for pointing users toward a list command, for example).

func AddJQFlag ¶

func AddJQFlag(cmd *cobra.Command)

AddJQFlag registers --jq on cmd and binds it to out.

func AddJSONFlag ¶

func AddJSONFlag(cmd *cobra.Command, out *bool)

AddJSONFlag registers --json on cmd and binds it to out.

func AppURL ¶

func AppURL(ctx context.Context, cmd *cobra.Command) (string, error)

func ConfirmOrForce ¶

func ConfirmOrForce(ctx context.Context, streams iostream.Streams, force bool, prompt string, abortErr, requireForceErr *clierrors.CLIError) error

ConfirmOrForce requires user confirmation of a destructive operation.

• If force is true, returns nil immediately (scripting / non-interactive path).
• In a TTY, shows prompt and returns abortErr if the user declines.
• Outside a TTY, returns requireForceErr with the standard --force suggestion appended so callers don't have to repeat it.

Construct abortErr and requireForceErr with domain-specific codes and messages; the standard suggestion text is added automatically to requireForceErr.

func GitDetectErr ¶

func GitDetectErr(err error, suggestions ...string) *clierrors.CLIError

GitDetectErr wraps a gitremote.Detect error into a structured CLIError.

The standard "run from inside a git repository" suggestion is always included as the first suggestion. Pass additional command-specific suggestions as variadic args (e.g. "Or specify the project with --project gh/org/repo").

func GroupRunE ¶

func GroupRunE(cmd *cobra.Command, args []string) error

GroupRunE is the RunE for group (parent) commands that have no action of their own. It shows help when invoked with no arguments and returns a structured error for unknown subcommands.

func IsSecureStorage ¶

func IsSecureStorage(cmd *cobra.Command) bool

func LoadClient ¶

func LoadClient(ctx context.Context, cmd *cobra.Command) (*apiclient.Client, error)

LoadClient reads the CLI config, validates that a token is present, and returns an authenticated API client. On failure it returns a structured CLIError ready to be returned directly from a RunE handler.

Honors a --config path set by the root PersistentPreRunE via WithConfigPath.

func RequireArgs ¶

func RequireArgs(args []string, names ...string) error

RequireArgs returns a structured CLIError if args contains fewer elements than the number of names provided. Each name describes an expected positional argument (e.g. "workflow-id", "resource-class") and appears in the error message as <name>.

Use alongside cobra.MaximumNArgs(N) so that too many args are still rejected by Cobra, while the missing-arg case produces a structured error from RunE.

func RequireFlag ¶

func RequireFlag(name string) error

RequireFlag returns a structured CLIError reporting that a required flag was not set. name is the long flag name without the leading dashes (e.g. "org-id").

func ResolveOrgID ¶

func ResolveOrgID(ctx context.Context, client *apiclient.Client, orgID, cmdName string) (string, error)

ResolveOrgID returns orgID as-is when non-empty. Otherwise it detects the project from the current git remote and resolves it through the API to recover the org UUID.

cmdName is included in the GitDetectErr suggestion text so users see the exact override flag for the command they invoked, e.g. "circleci certificate list".

func WithConfigPath ¶

func WithConfigPath(ctx context.Context, path string) context.Context

WithConfigPath returns a copy of ctx carrying the given config file path. The path is read by LoadClient to locate the config file.

func WriteJSON ¶

func WriteJSON(w io.Writer, v any) error

WriteJSON encodes v as indented JSON to w. Use streams.Out as the writer. Returns the encoder error, if any.