urfave

package
v0.7.17 Latest Latest
Warning

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

Go to latest
Published: Aug 10, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var Preflight = complete.Preflight

Preflight scans os.Args for completion flags, allowing completion to be handled before the CLI parser. This is useful for subcommand-based CLIs where the parser requires a subcommand but completion flags are standalone.

Returns a populated CompletionFlags, any positional args found after "--", and true if a completion flag was found. When ok is false, the caller should proceed with normal CLI parsing.

Functions

func CompletionCommand

func CompletionCommand(genFunc func() *complete.Generator) *clilib.Command

CompletionCommand returns a hidden urfave subcommand that prints clib-powered completion scripts. It replaces urfave's default shell completion behavior.

The genFunc is called at run time to build the generator, so the full command tree is available.

func Extend

func Extend(flag clilib.Flag, extra FlagExtra)

Extend attaches clib metadata to a urfave Flag.

cliurfave.Extend(repoFlag, cliurfave.FlagExtra{
	Group:       "Filters",
	Placeholder: "repo",
	Complete:    "predictor=repo",
})

Metadata is bound onto command-local metadata the first time clib walks a command tree. Pointer flags are keyed by identity; value flags fall back to type+name matching so custom non-comparable value flags still work.

func ExtendCommand

func ExtendCommand(cmd *clilib.Command, extra CommandExtra)

ExtendCommand attaches clib metadata to a urfave Command.

func FlagMeta

func FlagMeta(cmd *clilib.Command) []complete.FlagMeta

FlagMeta extracts completion metadata from a urfave command's flags. It reads flag properties via urfave interfaces and clib extras.

func HelpPrinter

func HelpPrinter(
	r *help.Renderer,
	sections func(cmd *clilib.Command) []help.Section,
	opts ...help.Option,
) func(io.Writer, string, any)

HelpPrinter returns a func(io.Writer, string, any) suitable for assigning to clilib.HelpPrinter (the global variable). The data parameter is the *Command. By default, the description blurb and examples are hidden on -h and shown on --help (examples last); pass help.WithAlwaysShowDescription and/or help.WithAlwaysShowExamples to disable this.

func Sections

func Sections(cmd *clilib.Command) []help.Section

Sections builds standard help sections from a urfave command. Extracts: Usage, Aliases, Commands, and grouped flag sections.

func SectionsWithOptions

func SectionsWithOptions(opts ...SectionsOption) func(*clilib.Command) []help.Section

SectionsWithOptions builds standard help sections from a urfave command using configurable behavior.

func Subcommands

func Subcommands(cmd *clilib.Command) []complete.SubSpec

Subcommands extracts subcommand completion specs from a urfave command tree. Each visible subcommand produces a SubSpec with its flags (excluding hidden flags and the built-in --help flag).

Types

type CSVFlag

type CSVFlag struct {
	Values []string
}

CSVFlag implements urfave/cli's Value interface for comma-separated values. Use with *clilib.GenericFlag{Name: "x", Value: &CSVFlag{}}.

func (*CSVFlag) Get

func (c *CSVFlag) Get() any

Get returns the underlying string slice.

func (*CSVFlag) Set

func (c *CSVFlag) Set(val string) error

Set appends comma-separated values, filtering empty entries.

func (*CSVFlag) String

func (c *CSVFlag) String() string

String returns the comma-separated string representation.

func (*CSVFlag) Type

func (c *CSVFlag) Type() string

Type returns the flag type name.

type CommandExtra

type CommandExtra struct {
	Alias    string // command invoked by this alias command
	PathArgs bool   // enable file completion for positional args
}

CommandExtra holds clib-specific metadata for a urfave Command.

type Completion

type Completion struct {
	// contains filtered or unexported fields
}

Completion manages hidden completion flags on a urfave command.

func NewCompletion

func NewCompletion(cmd *clilib.Command) *Completion

NewCompletion adds hidden completion flags to cmd and returns a Completion. Flags added: --@complete, --@shell, --install-completion, --uninstall-completion, --print-completion.

func (*Completion) Handle

func (c *Completion) Handle(
	gen *complete.Generator,
	handler complete.Handler,
	opts ...Option,
) (bool, error)

Handle checks whether a completion action was requested and executes it. Returns true if a completion action was handled (caller should exit). The handler callback is invoked for --@complete=<type> requests; it receives the completion type and resolved shell name.

type CompletionFlags

type CompletionFlags = complete.CompletionFlags

CompletionFlags is an alias for complete.CompletionFlags. See Preflight for pre-parse usage.

type FlagExtra

type FlagExtra struct {
	Complete       string         // completion directive (e.g. "predictor=repo")
	CompleteHidden bool           // still offer this flag in completions even when hidden from help
	Enum           []string       // enum values
	EnumDefault    string         // default enum value (highlighted by EnumStyleHighlightDefault)
	EnumHighlight  []string       // highlight hints for enum values
	EnumTerse      []string       // short descriptions for enum values (parallel to Enum)
	Extension      string         // file extension filter for completion (e.g. "yaml" or "yaml,yml")
	Group          string         // help section group
	HideLong       bool           // hide the long flag from help output
	HideShort      bool           // hide the short flag from help output
	Hint           string         // value type hint for completion (file, dir, command, user, host, url, email)
	NegativeDesc   string         // description for --no- variant (negatable flags)
	NegativeOnly   bool           // advertise only the --no- variant in help (negatable flags)
	NoIndent       bool           // suppress short-flag alignment indent in help
	Order          complete.Order // completion ordering mode
	Placeholder    string         // value placeholder (e.g. "repo")
	PositiveDesc   string         // description for positive variant (negatable flags)
	PositiveOnly   bool           // advertise only the positive variant in help (negatable flags)
	Terse          string         // very short description for completions
}

FlagExtra holds clib-specific metadata for a urfave Flag.

type Option

type Option func(*config)

Option configures Handle behavior.

func WithArgs

func WithArgs(args []string) Option

WithArgs passes preceding positional args to the completion handler.

func WithQuiet

func WithQuiet(quiet bool) Option

WithQuiet suppresses output during install/uninstall.

type SectionsOption

type SectionsOption func(*sectionsConfig)

SectionsOption configures urfave help-section generation.

func WithGlobalOptionsTitle added in v0.6.12

func WithGlobalOptionsTitle(title string) SectionsOption

WithGlobalOptionsTitle separates inherited flags under the given section title instead of the default merged-options layout.

func WithHideCommandAliases added in v0.7.6

func WithHideCommandAliases() SectionsOption

WithHideCommandAliases omits command aliases from help output.

func WithInlineCommandAliases added in v0.7.6

func WithInlineCommandAliases() SectionsOption

WithInlineCommandAliases keeps alias commands in the Commands section instead of placing them in a separate Aliases section.

func WithOptionsTitle added in v0.6.12

func WithOptionsTitle(title string) SectionsOption

WithOptionsTitle sets the section title for local and merged flags instead of the default "Options".

func WithPreservePlaceholders

func WithPreservePlaceholders() SectionsOption

WithPreservePlaceholders keeps placeholders exactly as provided by clib metadata. By default, explicit urfave flag placeholders are lowercased for consistency with clib's help style.

func WithRawUsage

func WithRawUsage() SectionsOption

WithRawUsage passes cmd.ArgsUsage through to the usage line verbatim instead of parsing it into structured Args. Use this for urfave commands whose ArgsUsage contains shell metacharacters (pipes, parens, ellipses) that clib's arg grammar would otherwise mangle.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL