Complete API reference for nyxstack/cli.
func Root(name string) *CommandCreates a root command (entry point of your CLI).
func Cmd(name string) *CommandCreates a regular subcommand.
func (c *Command) Description(desc string) *CommandSets the command description (shown in help).
func (c *Command) Hidden() *CommandHides the command from help output.
func (c *Command) Show() *CommandMakes a hidden command visible again.
func (c *Command) Flag(ptr interface{}, name, short string, defaultValue interface{}, usage string) *CommandAdds a flag to the command.
ptr: Pointer to variable that will receive the flag valuename: Long flag name (e.g., "verbose")short: Short flag name (e.g., "v"), use "" for nonedefaultValue: Default value if flag not providedusage: Help text for the flag
func (c *Command) FlagRequired(ptr interface{}, name, short string, defaultValue interface{}, usage string) *CommandAdds a required flag. Returns error if not provided.
func (c *Command) FlagHidden(ptr interface{}, name, short string, defaultValue interface{}, usage string) *CommandAdds a flag that's hidden from help output.
func (c *Command) Flags(structPtr interface{}) *CommandBinds struct fields as flags using struct tags.
Example:
type Config struct {
Host string `cli:"host,h" default:"localhost" usage:"Server host"`
Port int `cli:"port,p" default:"8080" usage:"Server port"`
}
var config Config
cmd.Flags(&config)func (c *Command) Arg(name, description string, required bool) *CommandAdds a positional argument.
name: Argument name (for help text)description: Argument descriptionrequired: Whether argument is required
func (c *Command) PersistentPreRun(fn ActionFunc) *CommandRuns before action, for this command and all children.
func (c *Command) PreRun(fn ActionFunc) *CommandRuns before action, only for this command.
func (c *Command) Action(fn ActionFunc) *CommandMain command logic.
func (c *Command) PostRun(fn ActionFunc) *CommandRuns after action, only for this command.
func (c *Command) PersistentPostRun(fn ActionFunc) *CommandRuns after action, for this command and all children.
ActionFunc signature:
func(ctx context.Context, cmd *Command, args ...interface{}) errorfunc (c *Command) AddCommand(cmd *Command) *CommandAdds a subcommand.
func (c *Command) Execute() errorExecutes the command with os.Args.
func (c *Command) ExecuteContext(ctx context.Context) errorExecutes with a context (for cancellation/timeout).
func (c *Command) ExecuteWithArgs(args []string) errorExecutes with custom arguments (useful for testing).
func (c *Command) GetName() stringReturns command name.
func (c *Command) GetDescription() stringReturns command description.
func (c *Command) GetParent() *CommandReturns parent command (nil for root).
func (c *Command) GetCommands() map[string]*CommandReturns map of subcommands.
func (c *Command) GetArgs() []ArgumentReturns list of arguments.
func (c *Command) IsHidden() boolReturns whether command is hidden.
func (c *Command) ShowHelp()Displays help for this command.
func (c *Command) DisableHelp() *CommandDisables automatic help flag for this command.
func (c *Command) EnableHelp() *CommandRe-enables automatic help flag.
func (c *Command) SetHelpFlag(name, short string) *CommandCustomizes the help flag name.
func (c *Command) IsHelpEnabled() boolReturns whether help is enabled.
func (f *Flag) GetNames() []stringReturns all flag names (long and short).
func (f *Flag) GetType() stringReturns flag type as string ("string", "int", "bool", etc.).
func (f *Flag) PrimaryName() stringReturns the long flag name.
func (f *Flag) ShortName() stringReturns the short flag name (empty if none).
func (f *Flag) GetDefault() interface{}Returns the default value.
func (f *Flag) GetUsage() stringReturns the usage/help text.
func (f *Flag) GetValue() interface{}Returns the current flag value.
func (f *Flag) IsRequired() boolReturns whether flag is required.
func (f *Flag) IsHidden() boolReturns whether flag is hidden.
func (f *Flag) IsSet() boolReturns whether flag was explicitly set by user.
func (f *Flag) HasName(name string) boolChecks if flag has the given name (long or short).
func NewFlagSet() *FlagSetCreates a new flag set (usually not needed, commands create their own).
func (fs *FlagSet) Add(ptr interface{}, name, short string, defaultValue interface{}, usage string) *FlagAdds a flag to the set.
func (fs *FlagSet) GetFlag(name string) *FlagGets a flag by name (long or short).
func (fs *FlagSet) GetFlags(names ...string) []*FlagGets multiple flags by name.
func (fs *FlagSet) GetAll() []*FlagReturns all flags in the set.
func (fs *FlagSet) Parse(args []string) ([]string, error)Parses flags from arguments, returns remaining args.
func (fs *FlagSet) BindStruct(structPtr interface{})Binds struct fields as flags using tags.
type Argument struct {
Name string // Argument name
Description string // Help text
Required bool // Whether required
}func AddCompletion(rootCmd *Command)Adds completion subcommands for all shells (bash, zsh, fish, powershell).
type BashCompletion struct{}
type ZshCompletion struct{}
type FishCompletion struct{}
type PowerShellCompletion struct{}Each implements:
func (c *Completion) GetCompletions(cmd *Command, args []string) []string
func (c *Completion) Register(cmd *Command)
func (c *Completion) GenerateScript(cmd *Command) stringtype CommandNotFoundError struct {
Name string
}
type ArgumentError struct {
Message string
}
type FlagError struct {
Message string
}All implement error interface with custom Error() messages.
Flags and arguments support automatic type conversion for:
- Strings:
string - Integers:
int,int8,int16,int32,int64 - Unsigned:
uint,uint8,uint16,uint32,uint64 - Floats:
float32,float64 - Boolean:
bool - Duration:
time.Duration - Arrays:
[]string,[]int, etc. (via repeated flags)
// String
var name string
cmd.Flag(&name, "name", "n", "default", "Name")
// Integer
var port int
cmd.Flag(&port, "port", "p", 8080, "Port")
// Boolean
var verbose bool
cmd.Flag(&verbose, "verbose", "v", false, "Verbose")
// Duration
var timeout time.Duration
cmd.Flag(&timeout, "timeout", "t", 30*time.Second, "Timeout")
// Array
var tags []string
cmd.Flag(&tags, "tag", "", nil, "Tags")Always return errors from actions:
cmd.Action(func(ctx context.Context, cmd *Command) error {
if err := doWork(); err != nil {
return fmt.Errorf("work failed: %w", err)
}
return nil
})Use context for cancellation:
cmd.Action(func(ctx context.Context, cmd *Command) error {
select {
case <-ctx.Done():
return ctx.Err()
case result := <-doWork():
return nil
}
})- Use lowercase with hyphens:
--api-key - Provide short forms for common flags:
-v,-p - Be consistent across commands
- Use lowercase:
deploynotDeploy - Use verbs for actions:
start,stop,deploy - Group related commands:
database migrate,database rollback
See the examples/ directory for complete working examples of all features.
- Start with Quick Start
- Learn about Commands
- Explore Flags and Arguments
- Understand Lifecycle Hooks