cli

README

cli

Go package for building cli tool that can load program configuration from multiple sources:

• command flags
• Environment

Usage

Define a Go struct that uses field tags to describe a command configuration:

type config struct {
	String string `cli:"string" env:"CONF_STRING" help:"A string argmument for demo purpose."`
	Int    int    `cli:"int"    env:"CONF_INT"    help:"A int argmument for demo purpose."`
	Help   bool   `cli:"h"      env:"-"           help:"Show help."`
}

Field Tag	Description
cli	Maps a cli flag for the given field.
env	Maps environment variable for the given field.
help	Setup a description for the given field when using the help flag -h

Load the config:

func main() {
	cfg := config{
		Int: 42, // Set 42 as default value for Int field.
	}

	// Registers the config.
	cli.Register().
		Help("A demo cli program").
		Options(&cfg)

	cli.Load() // Stores corresponding cli and env into cfg.

	fmt.Println(cfg)
}

command output with -h flag:

▶ ./my-program -h
Usage:

    hds [options]

Description:

    A demo cli program

Options:

    -string  string    A string argmument for demo purpose.
                       Env:     CONF_STRING

    -int     int       A int argmument for demo purpose.
                       Env:     CONF_INT
                       Default: 42

    -h       bool      Show help.

Documentation

Overview

Package cli is a package to build CLI programs.

eg:

 func main() {
     opts := struct {
	        Foo string `env:"FOO" help:"A simple string."`
		    Bar int    `env:"BAR" help:"A simple integer."`
     }{
		    Foo: "foo",
		    Bar: 42,
     }

     ctx, cancel := cli.ContextWithSignals(context.Background(),
         os.Interrupt,
		    syscall.SIGTERM,
     )
     defer cancel()

     cli.Register().
		    Help("A simple command").
		    Options(&opts)

     cli.Register("hello").
		    Help("A sub command").
		    Options(&opts)

     cli.Register("world").
		    Help("Another sub command").
		    Options(&opts)

     switch cli.Load() {
	    case "hello":
		    helloCmd(ctx, opts)

     case "world":
		    worldCmd(ctx, opts)

	    default:
		    defaultCmd(ctx, opts)
	    }
 }

Index

• func ContextWithSignals(parent context.Context, sig ...os.Signal) (ctx context.Context, cancel func())
• func Error(err error)
• func Load() (cmd string)
• func Usage()
• type Command
  • func Register(cmd ...string) Command

Functions

func ContextWithSignals

func ContextWithSignals(parent context.Context, sig ...os.Signal) (ctx context.Context, cancel func())

ContextWithSignals returns a copy of the parent context that gets canceled when one of the specified signals is emitted. If no signals are provided, all incoming signals will cancel the context.

Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this Context complete.

func Error

func Error(err error)

Error prints the given error and exit the program with code -1.

func Load

func Load() (cmd string)

Load loads the registered command that matches the program args. If defined, environment variables and flags are loaded in the command options.

It prints the command usage and exits the program with code -1 when an error occurs.

func Usage

func Usage()

Usage prints the loaded command usage. It panics when called before the Load function.

Types

type Command

type Command interface {
	// Sets the command help description.
	Help(string) Command

	// Sets the command options with the given receiver. The receiver must be a
	// pointer to a struct.
	Options(interface{}) Command
}

Command is the interface that describes a command.

func Register

func Register(cmd ...string) Command

Register registers and returns the named command.