cli

README

cli

Reduce boiler plate needed on each new Golang main functions (Command Line Interface) for both tools and servers (use fortio.org/scli ServerMain() for server)

It abstracts the repetitive parts of a main() command line tool, flag parsing, usage, etc...

You can see real use example in a tool like multicurl or a server like proxy.

It also supports (sub)commands style (where there is a word/command before the flags and remaining arguments, fortio uses that mode).

Tool Example

Client/Tool example (no dynamic flag url or config) sampleTool

Code as simple as

import (
	"flag"
	"os"

	"fortio.org/cli"
	"fortio.org/log"
)

func main() {
	myFlag := flag.String("myflag", "default", "my flag")
	cli.MinArgs = 2
	cli.MaxArgs = 4
	cli.Main() // Will have either called cli.ExitFunction or everything is valid
	// Next line output won't show when passed -quiet
	log.Infof("Info test, -myflag is %q", *myFlag)
	// This always shows
	log.Printf("Hello world, version %s, args %v", cli.ShortVersion, flag.Args())
	// This shows and is colorized and structured, unless loglevel is set to critical.
	log.S(log.Error, "Error test",
		log.Str("myflag", *myFlag),
		log.Attr("num_args", len(flag.Args())),
		log.Attr("args", flag.Args()))
}

$ sampleTool a
sampleTool 1.2.0 usage:
	sampleTool [flags] arg1 arg2 [arg3...arg4]
or 1 of the special arguments
	sampleTool {help|version|buildinfo}
flags:
  -logger-force-color
    	Force color output even if stderr isn't a terminal
  -logger-no-color
    	Prevent colorized output even if stderr is a terminal
  -loglevel level
    	log level, one of [Debug Verbose Info Warning Error Critical Fatal] (default Info)
  -myflag string
    	my flag (default "default")
  -quiet
    	Quiet mode, sets loglevel to Error (quietly) to reduces the output
At least 2 arguments expected, got 1

Since v1.3, the above is colorized on a terminal and looks like this:

or normal case:

Old style, no colors:

$ sampleTool -logger-no-color a b
17:20:41 [I] Info test, -myflag is "default"
17:20:41 Hello world, version dev, args [a b]
17:20:41 [E] Error test, myflag="default", num_args="2", args="[a b]"

Additional builtins

buildinfo

e.g

% go install github.com/fortio/multicurl@latest
go: downloading github.com/fortio/multicurl v1.10.1
% multicurl buildinfo
1.10.1 h1:h9yM3XplwG7JWtVaSS0eJPiDmCJfnxvj3w+yoAMWMo4= go1.19.6 arm64 darwin
go	go1.19.6
path	github.com/fortio/multicurl
mod	github.com/fortio/multicurl	v1.10.1	h1:h9yM3XplwG7JWtVaSS0eJPiDmCJfnxvj3w+yoAMWMo4=
dep	fortio.org/cli	v0.6.1	h1:V9L6ly4oz4fJjeQ5745FulIMsFAwFZvLPSUN+cKUrKk=
dep	fortio.org/log	v1.2.2	h1:vs42JjNwiqbMbacittZjJE9+oi72Za6aekML9gKmILg=
dep	fortio.org/version	v1.0.2	h1:8NwxdX58aoeKx7T5xAPO0xlUu1Hpk42nRz5s6e6eKZ0=
build	-compiler=gc
build	CGO_ENABLED=1
build	CGO_CFLAGS=
build	CGO_CPPFLAGS=
build	CGO_CXXFLAGS=
build	CGO_LDFLAGS=
build	GOARCH=arm64
build	GOOS=darwin

help

% multicurl help
Fortio multicurl 1.10.1 usage:
	multicurl [flags] url
or 1 of the special arguments
	multicurl {help|version|buildinfo}
flags:
[...]
  -logger-force-color
    	Force color output even if stderr isn't a terminal
  -logger-no-color
    	Prevent colorized output even if stderr is a terminal
  -loglevel level
    	log level, one of [Debug Verbose Info Warning Error Critical Fatal] (default Info)
  -quiet
    	Quiet mode, sets loglevel to Error (quietly) to reduces the output

version

Short 'numeric' version (v skipped, useful for docker image tags etc)

 % multicurl version
1.10.1

https/tls in FROM scratch docker images

You should always try to use FROM scratch Docker images when possible, it's one of the strength of go.

Using this fortio.org/cli as a base makes it work for outcalls to internet valid TLS certs (e.g. https). It does this by defaulting to the bundle provided by golang.org/x/crypto/x509roots/fallback automatically.

See https://github.com/fortio/multicurl for a good example.

If you do not want this behavior, build using -tag=no_tls_fallback.

Documentation

Overview

Package cli contains utilities for command line tools and server main()s to handle flags, arguments, version, logging (fortio.org/log), etc... Configure using the package variables (at minimum MinArgs unless your binary only accepts flags), setup additional flag before calling Main or fortio.org/scli.ServerMain for configmap and dynamic flags setup. Also supports (sub)commands style, see CommandBeforeFlags and Command.

Index

• Variables
• func ChangeFlagsDefault(newDefault string, flagNames ...string) error
• func ColorJoin(color string, args ...string) string
• func EnvHelp(w io.Writer)
• func ErrUsage(msg string, args ...any)
• func Main()
• func Plural(i int, noun string) string
• func PluralExt(i int, noun string, ext string) string

Variables

var (
	// Out parameters:
	// *Version will be filled automatically by the cli package, using [fortio.org/version.FromBuildInfo()].
	ShortVersion string // x.y.z from tag/install
	LongVersion  string // version plus go version plus OS/arch
	FullVersion  string // LongVersion plus build date and git sha
	Command      string // first argument, if [CommandBeforeFlags] is true.
	// Following can/should be specified.
	ProgramName string // Used at the beginning of Usage()
	// Optional for programs using subcommand, command will be set in [Command].
	// If you wish to replace the help default colorize `command` with something else set CommandHelp.
	CommandBeforeFlags bool
	// Cli usage/arguments example, ie "url1..." program name and "[flags]" will be added"
	// can include \n for additional details in the Usage() before the flags are dumped.
	ArgsHelp string
	// Command help will be used instead of purple "command " in help text for cli that have a
	// command before the flags (when [CommandBeforeFlags] is true). For instance you could use
	// cli.CommandHelp = "{" + cli.ColorJoin(log.Colors.Purple, "a", "b", "c") + "}"
	// for colorize {a|b|c} in the help before [flags].
	CommandHelp string
	MinArgs     int // Minimum number of arguments expected, not counting (optional) command.
	MaxArgs     int // Maximum number of arguments expected. 0 means same as MinArgs. -1 means no limit.
	// If not set to true, will setup static loglevel flag and logger output for client tools.
	ServerMode = false
	// Override this to change the exit function (for testing), will be applied to log.Fatalf too.
	ExitFunction = os.Exit
	// Hook to call before flag.Parse() - for instance to use ChangeFlagDefaults for logger flags etc.
	BeforeFlagParseHook = func() {}

	// List of functions to call for env help.
	EnvHelpFuncs = []func(w io.Writer){log.EnvHelp}
)

Configuration for your Main() or ServerMain() function. These variables is how to setup the arguments, flags and usage parsing for Main and [ServerMain]. At minium set the MinArgs should be set.

Functions

func ChangeFlagsDefault

func ChangeFlagsDefault(newDefault string, flagNames ...string) error

ChangeFlagsDefault sets some flags to a different default. Will return error if the flag is not found and value can't be set (caller should likely log.Fatalf if that happens as it's a typo/bug).

func ColorJoin

func ColorJoin(color string, args ...string) string

func EnvHelp

func EnvHelp(w io.Writer)

func ErrUsage

func ErrUsage(msg string, args ...any)

Show usage and error message on stderr and calls ExitFunction with code 1.

func Main

func Main()

Main handles your commandline and flag parsing. Sets up flags first then call Main. For a server with dynamic flags, call ServerMain instead. Will either have called ExitFunction (defaults to os.Exit) or returned if all validations passed.

func Plural

func Plural(i int, noun string) string

Plural adds an "s" to the noun if i is not 1.

func PluralExt

func PluralExt(i int, noun string, ext string) string

PluralExt returns the noun with an extension if i is not 1. Eg:

PluralExt(1, "address", "es") // -> "address"
PluralExt(3 /* or 0 */, "address", "es") // -> "addresses"