cmdutil

package
v2.11.2 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddForceFlag 

func AddForceFlag(cmd *cobra.Command, force *bool)

AddForceFlag adds the --force/-f flag to a command.

func AddOutputFlag 

func AddOutputFlag(cmd *cobra.Command, format *string)

AddOutputFlag registers --output/-o as a local flag on the given command.

The root command also registers --output/-o as a persistent flag, so every leaf command accepts it automatically. This helper is retained for backward compatibility with command handlers that want the flag's value bound to a local variable (and for unit tests that instantiate leaf commands in isolation, without the root). Local flags shadow the inherited persistent flag, so the end-user behavior is identical.

func AddPaginationFlags 

func AddPaginationFlags(cmd *cobra.Command, limit, offset *int)

AddPaginationFlags adds --limit and --offset flags to a command.

func BuildErrorEnvelope 

func BuildErrorEnvelope(err error) output.ErrorEnvelope

BuildErrorEnvelope produces a structured error payload suitable for JSON rendering. It reuses FormatError for the human-readable message and derives a stable code from the underlying api.APIError classification.

func CompleteActivities 

func CompleteActivities(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteActivities returns a completion function for the --activity flag.

func CompleteCategories 

func CompleteCategories(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteCategories returns a completion function for the --category flag. Requires --project to be set (or a default project in config).

func CompleteCustomFields added in v2.6.0 

func CompleteCustomFields(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteCustomFields returns a completion function for the custom-fields command argument. Hits the admin-only /custom_fields.json endpoint, so it silently returns no candidates when the authenticated user lacks access.

func CompleteGroups 

func CompleteGroups(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteGroups returns a completion function for the --group flag. Returns empty completions gracefully if the user lacks admin privileges.

func CompleteIssueListStatus 

func CompleteIssueListStatus(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteIssueListStatus returns a completion function for the --status flag on the issues list command, which also accepts special values.

func CompleteOpenVersions 

func CompleteOpenVersions(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteOpenVersions returns a completion function for the --version flag that only shows open and locked versions (excludes closed). Useful for create/update commands where closed versions aren't valid targets.

func CompleteOutputFormat 

func CompleteOutputFormat(_ *cobra.Command, _ []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteOutputFormat provides static completions for the --output flag.

func CompletePriorities 

func CompletePriorities(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompletePriorities returns a completion function for the --priority flag.

func CompleteProjects 

func CompleteProjects(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteProjects returns a completion function for the --project flag.

func CompleteRoles added in v2.6.0 

func CompleteRoles(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteRoles returns a completion function for role-related flags.

func CompleteStatuses 

func CompleteStatuses(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteStatuses returns a completion function for the --status flag.

func CompleteTrackers 

func CompleteTrackers(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteTrackers returns a completion function for the --tracker flag.

func CompleteUserStatus 

func CompleteUserStatus(_ *cobra.Command, _ []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteUserStatus provides static completions for user --status flag.

func CompleteUsers 

func CompleteUsers(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteUsers returns a completion function for user-related flags. "me" is always offered because the resolver handles it without listing users; the rest of the list comes from /users.json, which requires admin. Non-admin sessions degrade gracefully to just the "me" candidate.

func CompleteVersionSharing added in v2.4.0 

func CompleteVersionSharing(_ *cobra.Command, _ []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteVersionSharing provides static completions for version --sharing flag.

func CompleteVersionStatus 

func CompleteVersionStatus(_ *cobra.Command, _ []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteVersionStatus provides static completions for version --status flag.

func CompleteVersions 

func CompleteVersions(f *Factory) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CompleteVersions returns a completion function for the --version flag that shows all versions including closed ones. Requires --project to be set (or a default project in config).

func ConfirmAction 

func ConfirmAction(in io.Reader, errOut io.Writer, message string) bool

ConfirmAction prompts the user to confirm a destructive action. Returns true if the user confirms with "y" or "yes". If in is not interactive or the user declines, returns false.

func DefaultProject 

func DefaultProject(f *Factory, project string) string

DefaultProject returns the given project string if non-empty, otherwise falls back to the configured default project. If the config cannot be loaded the original (empty) value is returned.

func DefaultProjectID 

func DefaultProjectID(ctx context.Context, f *Factory, project string) (string, error)

DefaultProjectID applies the default-project fallback and resolves to a numeric ID string. Returns ("", nil) when no project is specified.

func DefaultProjectIdentifier 

func DefaultProjectIdentifier(ctx context.Context, f *Factory, project string) (string, error)

DefaultProjectIdentifier applies the default-project fallback and resolves to the canonical identifier. Returns ("", nil) when no project is specified.

func DetectContentType added in v2.6.0 

func DetectContentType(f *os.File, path string) string

DetectContentType resolves a MIME type from the file extension, falling back to sniffing the first 512 bytes. The file position is left unspecified; the caller must seek before reading the file for upload.

func FormatError 

func FormatError(err error) string

FormatError converts an API error into a user-friendly message.

func HandleEmpty 

func HandleEmpty[T any](p output.Printer, items []T, noun string) bool

HandleEmpty checks whether items is empty. For empty slices it emits an empty JSON array (when the output format is JSON) or a warning (for other formats) and returns true. The caller should return nil when true.

func OpsLimit added in v2.5.0 

func OpsLimit(cliLimit int) int

OpsLimit translates a CLI --limit value to the convention used by the ops layer. The CLI treats --limit 0 as "no limit" while ops applies an MCP-safety default of 50 for zero. Any caller that wants to honor the CLI semantics passes its raw flag value through OpsLimit before constructing an ops input.

func ParseCustomFieldValues added in v2.6.0 

func ParseCustomFieldValues(ctx context.Context, client *api.Client, raws []string) (map[string]string, error)

ParseCustomFieldValues parses repeated --custom-field key=value entries into the Redmine-expected map keyed by stringified custom-field ID. Numeric keys are passed through; non-numeric keys are resolved by name against /custom_fields.json (admin-only) via a single batch lookup.

Multi-value (Multiple=true) custom fields are not supported here yet — see issue tracker.

func ParseKeyValuePairs added in v2.6.0 

func ParseKeyValuePairs(raws []string, flagName string) (map[string]string, error)

ParseKeyValuePairs parses repeated `key=value` flag inputs into a map. The flagName is used to build clear error messages ("--filter %q must be key=value"). Empty keys and missing `=` are rejected.

func PrepareInteractiveCommand 

func PrepareInteractiveCommand(cmd *cobra.Command, f *Factory) error

PrepareInteractiveCommand opts a command out of structured output modes. It rejects an explicitly requested --output flag and otherwise forces the command to render using the default interactive/table path, ignoring any configured output_format.

func RenderCollection 

func RenderCollection[T any](printer output.Printer, items []T, headers []string, rowBuilder RowBuilder[T])

RenderCollection renders a simple collection in JSON, CSV, or table form. It is intended for list-style commands whose formats differ only in row styling, not in schema.

func RequireProjectIdentifier 

func RequireProjectIdentifier(ctx context.Context, f *Factory, project string) (string, error)

RequireProjectIdentifier applies the default-project fallback, ensures a project was provided, and resolves to the canonical identifier.

func ResolveDateKeyword added in v2.4.0 

func ResolveDateKeyword(input string) string

ResolveDateKeyword expands the `today` keyword to today's date in the YYYY-MM-DD format the Redmine API expects. Any other input (including the empty string and a plain ISO date) is returned unchanged so callers can keep their existing defaulting logic.

func ResolveProjectID 

func ResolveProjectID(ctx context.Context, f *Factory, input string) (string, error)

ResolveProjectID resolves a project input to its numeric ID string.

func ResolveProjectIdentifier 

func ResolveProjectIdentifier(ctx context.Context, f *Factory, input string) (string, error)

ResolveProjectIdentifier resolves a project input to its canonical identifier.

func SaveAttachmentToDir added in v2.8.0 

func SaveAttachmentToDir(ctx context.Context, client *api.Client, att *models.Attachment, dir string) (string, int64, error)

SaveAttachmentToDir streams an attachment into dir using its real filename and returns the path written and the number of bytes streamed. The directory is created if it does not exist. The server-supplied filename is reduced to its base component so a malicious or malformed name (e.g. one containing "../") cannot escape dir.

func SaveAttachmentToFile added in v2.8.0 

func SaveAttachmentToFile(ctx context.Context, client *api.Client, att *models.Attachment, path string) (int64, error)

SaveAttachmentToFile streams an attachment to the exact path given and returns the number of bytes written. The parent directory must already exist. The file is created (or truncated) with 0o644 permissions.

func UploadAttachments 

func UploadAttachments(ctx context.Context, client *api.Client, paths []string) ([]models.Upload, error)

UploadAttachments uploads each given file path and returns Upload references suitable for inclusion in an issue create/update payload.

func WarnPagination 

func WarnPagination(p output.Printer, r PaginationResult)

WarnPagination emits a pagination warning when there are more results than shown. No warning is emitted when limit is 0 (all results requested) or when the output format is JSON.

Types

type Factory 

type Factory struct {
	ConfigPath string
	Verbose    bool

	// Runtime overrides from CLI flags (highest precedence).
	ProfileOverride string
	ServerOverride  string
	APIKeyOverride  string
	NoColorOverride bool

	// ReadOnly, when non-nil, is the --read-only flag value and overrides
	// both REDMINE_READ_ONLY and the per-profile config (highest precedence).
	ReadOnly *bool

	// OutputFormat is set by the root persistent --output/-o flag and used
	// as the default format when commands call Printer("").
	OutputFormat string

	IOStreams *IOStreams
	// contains filtered or unexported fields
}

Factory provides lazy access to configuration, API client, and output printer.

func NewFactory 

func NewFactory() *Factory

NewFactory creates a new Factory with default I/O streams.

func (*Factory) ApiClient 

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

ApiClient returns an API client (cached after first call).

func (*Factory) Config 

func (f *Factory) Config() (*config.Config, error)

Config returns the loaded configuration (cached after first call). CLI flag overrides carry the highest precedence: ServerOverride and APIKeyOverride are resolved inside Load (before any keyring lookup), while NoColorOverride is applied afterward.

func (*Factory) DebugLogger 

func (f *Factory) DebugLogger() *debug.Logger

DebugLogger returns the debug logger, creating it on first call.

func (*Factory) Printer 

func (f *Factory) Printer(format string) output.Printer

Printer creates and returns a new output printer for the given format.

type IOStreams 

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

IOStreams holds the standard I/O streams.

type PaginationResult 

type PaginationResult struct {
	Shown  int    // Number of items displayed
	Total  int    // Total count from the API
	Limit  int    // The --limit value used
	Offset int    // The --offset value used
	Noun   string // Plural noun for the message, e.g. "issues"
}

PaginationResult holds the information needed to emit a pagination warning.

type RowBuilder 

type RowBuilder[T any] func(item T, styled bool) []string

RowBuilder builds one output row for an item. When styled is true, callers may apply ANSI/color formatting suitable for table output.

type SilentError 

type SilentError struct{ Code int }

SilentError is returned when the error message has already been printed or should be suppressed. main.go will still exit with the given code.

func (*SilentError) Error 

func (e *SilentError) Error() string

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.