urfave

Documentation

Overview

Package urfave adapts Conductor to urfave/cli v3 CLIs: one call wires themed help, shell completions, standard flags, version output and update notifications onto an existing root command, mirroring the conventions of clib's cli/urfave package.

Index

• func UpdateCommand(app *conductor.Runtime) *clilib.Command
• func VersionCommand(app *conductor.Runtime) *clilib.Command
• type Flags
  • func (f *Flags) ConductorFlags() conductor.Flags
• type Option
  • func WithAlwaysShowDescription() Option
  • func WithAlwaysShowExamples() Option
  • func WithExitCode(fn func(error) int) Option
  • func WithGenerator(fn func(*complete.Generator)) Option
  • func WithSections(opts ...cliburfave.SectionsOption) Option
  • func WithSelfUpdate() Option
  • func WithUpdateCommand() Option
  • func WithVersionCommand() Option
  • func WithoutStandardFlags() Option
• type Program
  • func New(app *conductor.Runtime, root *clilib.Command, opts ...Option) *Program
  • func (p *Program) Generator() *complete.Generator
  • func (p *Program) Run(ctx context.Context, args []string) int

Functions

func UpdateCommand

func UpdateCommand(app *conductor.Runtime) *clilib.Command

UpdateCommand returns the standard self-update subcommand. It dispatches on App.Updater's install method (brew, goinstall or github); tools distributed another way provide their own update command instead.

func VersionCommand

func VersionCommand(app *conductor.Runtime) *clilib.Command

VersionCommand returns the standard `version` subcommand.

Types

type Flags

type Flags struct {
	Verbose bool
	Quiet   bool
	Color   clog.ColorMode
}

Flags are the standard flags: verbosity and color. New prepends them to the root command's flags and applies them in the chained Before hook.

func (*Flags) ConductorFlags

func (f *Flags) ConductorFlags() conductor.Flags

ConductorFlags implements conductor.FlagSource.

type Option

type Option func(*Program)

Option configures New.

func WithAlwaysShowDescription

func WithAlwaysShowDescription() Option

WithAlwaysShowDescription shows the description blurb on short help (-h) as well as long help (--help). By default the description is hidden on -h.

func WithAlwaysShowExamples

func WithAlwaysShowExamples() Option

WithAlwaysShowExamples shows the Examples section on short help (-h) as well as long help (--help). By default examples are hidden on -h.

func WithExitCode

func WithExitCode(fn func(error) int) Option

WithExitCode maps command errors to exit codes; see conductor.ExitCode.

func WithGenerator

func WithGenerator(fn func(*complete.Generator)) Option

WithGenerator customises the completion generator before completion actions run, e.g. to add dynamic argument specs.

func WithSections

func WithSections(opts ...cliburfave.SectionsOption) Option

WithSections configures the help section builder.

func WithSelfUpdate

func WithSelfUpdate() Option

WithSelfUpdate adds the hidden --self-update flag for CLIs without subcommands, which have no room for an update command. Program.Run intercepts the flag before urfave parses and performs the self-update via App.Updater; it is mutually exclusive with every other argument.

func WithUpdateCommand

func WithUpdateCommand() Option

WithUpdateCommand adds the standard Homebrew `update` subcommand.

func WithVersionCommand

func WithVersionCommand() Option

WithVersionCommand adds the standard `version` subcommand.

func WithoutStandardFlags

func WithoutStandardFlags() Option

WithoutStandardFlags skips registering --verbose/--quiet/--color, for tools whose own flags or output policy already cover those semantics.

type Program

type Program struct {
	Runtime    *conductor.Runtime
	Root       *clilib.Command
	Completion *cliburfave.Completion
	Flags      *Flags
	// contains filtered or unexported fields
}

Program is the assembled urfave CLI. All fields are exported and may be customised between New and Program.Run.

func New

func New(app *conductor.Runtime, root *clilib.Command, opts ...Option) *Program

New wires Conductor onto root: identity defaults from the App, themed help (via the package-global clilib.HelpPrinter), prepended standard flags, a -V/--version flag (replacing urfave's -v alias, which the verbose flag claims), completion flags, and a chained Before hook that applies the standard flags and starts the update notification.

func (*Program) Generator

func (p *Program) Generator() *complete.Generator

Generator builds the completion generator from the assembled command tree.

func (*Program) Run

func (p *Program) Run(ctx context.Context, args []string) int

Run is the one-call happy path: completion preflight, run, deferred update-hint flush, and exit code mapping. args is the full argument vector including the program name (os.Args, urfave's convention). The caller passes the result to os.Exit.