cobra

Documentation

Overview

Package cobra adapts Conductor to cobra-based 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/cobra package.

Index

• func UpdateCommand(app *conductor.Runtime) *cobralib.Command
• func VersionCommand(app *conductor.Runtime) *cobralib.Command
• type Flags
  • func (f *Flags) ConductorFlags() conductor.Flags
  • func (f *Flags) Register(fs *pflag.FlagSet)
• 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 ...clibcobra.SectionsOption) Option
  • func WithSelfUpdate() Option
  • func WithUpdateCommand() Option
  • func WithVersionCommand() Option
  • func WithoutStandardFlags() Option
• type Program
  • func New(app *conductor.Runtime, root *cobralib.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) *cobralib.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) *cobralib.Command

VersionCommand returns the standard `version` subcommand.

Types

type Flags

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

Flags are the standard persistent flags: verbosity and color. New registers them on the root command's persistent flag set and applies them in the chained PersistentPreRunE.

func (*Flags) ConductorFlags

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

ConductorFlags implements conductor.FlagSource.

func (*Flags) Register

func (f *Flags) Register(fs *pflag.FlagSet)

Register adds --verbose/-v, --quiet/-q and --color to fs. Flags the command already defines are left untouched - a tool with its own --quiet semantics keeps them, and the corresponding Flags field simply stays zero. A shorthand already claimed by another flag registers the long form only.

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 ...clibcobra.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 cobra executes 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 (a subcommand's local shorthand may also conflict with the persistent ones).

type Program

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

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

func New

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

New wires Conductor onto root: identity defaults from the App, themed help, persistent standard flags, a -V/--version flag, completion flags, and a chained PersistentPreRunE that applies the standard flags and starts the update notification once the command is resolved. Add subcommands to root before or after New; the completion generator is built at Run time.

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, execute, deferred update-hint flush, and exit code mapping. The caller passes the result to os.Exit.