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) (string, error)

func ConfigPath ¶

func ConfigPath(cmd *cobra.Command) string

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 ContextsURL ¶

func ContextsURL(appURL, orgSlug string) (string, error)

ContextsURL returns the CircleCI contexts settings page URL for the given org slug.

func DeployURL ¶

func DeployURL(appURL string, proj *apiclient.ProjectInfo) string

DeployURL returns the CircleCI deploys page URL for the given project.

func DisableTelemetry ¶

func DisableTelemetry(cmd *cobra.Command)

func DisableTelemetryForSubcommands ¶

func DisableTelemetryForSubcommands(cmd *cobra.Command)

func GetAgentName ¶

func GetAgentName(ctx context.Context) string

func GetConfig ¶

func GetConfig(ctx context.Context) *config.Config

func GetVersion ¶

func GetVersion(ctx context.Context) string

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) (*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 ParseSlug ¶

func ParseSlug(slug string) (vcs, org, repo string, err error)

ParseSlug splits a project slug "vcs/org/repo" into its three components.

func PipelinesURL ¶

func PipelinesURL(appURL, slug string) (string, error)

PipelinesURL returns the CircleCI pipelines page URL for the given project slug.

func PipelinesURLForBranch ¶

func PipelinesURLForBranch(appURL, slug, branch string) (string, error)

PipelinesURLForBranch returns the CircleCI pipelines page URL filtered to a specific branch.

func ProjectURL ¶

func ProjectURL(appURL, slug string) (string, error)

ProjectURL returns the CircleCI project page URL for the given project slug.

func RecordTelemetry ¶

func RecordTelemetry(cmd *cobra.Command, telemetry tracker)

func RecordTelemetryForSubcommands ¶

func RecordTelemetryForSubcommands(cmd *cobra.Command, telemetry tracker)

func RecordTelemetryNow ¶

func RecordTelemetryNow(cmd *cobra.Command, telemetry tracker)

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 ResolveProjectID ¶

func ResolveProjectID(ctx context.Context, client *apiclient.Client, projectSlug, projectID string) (string, error)

ResolveProjectID returns projectID as-is when non-empty. Otherwise it resolves the project from the slug (--project flag or git remote) to recover its UUID.

func ResolveProjectSlug ¶

func ResolveProjectSlug(projectSlug string) (string, error)

ResolveProjectSlug returns projectSlug as-is when non-empty. Otherwise it detects the slug from the git remote. Unlike ResolveProjectID this does not make an API call and does not return a UUID — use it for endpoints that require a slug in the path (e.g. POST /project/{vcs}/{org}/{repo}/pipeline/run).

func RunnersURL ¶

func RunnersURL(appURL, orgSlug string) (string, error)

RunnersURL returns the CircleCI runners inventory page URL for the given org slug.

func VCSSlug ¶

func VCSSlug(provider string) string

VCSSlug maps API provider strings to the slug prefix used in CircleCI URLs (e.g. "GitHub" → "gh").

func WithAgentName ¶

func WithAgentName(ctx context.Context, name string) context.Context

func WithConfig ¶

func WithConfig(ctx context.Context, cfg *config.Config) context.Context

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

func WithVersion ¶

func WithVersion(ctx context.Context, version string) context.Context

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.