README
¶
Boilerplate combining Kong CLI argument parsing with zerolog logging
A Go package providing boilerplate combining Kong CLI argument parsing with zerolog logging.
Features:
- Config (from files, CLI arguments, and environment variables) is parsed into a struct based on struct tags, powered by Kong.
- JSON-based and pretty-printed logging, powered by zerolog.
- Support for built-time version variables and CLI flag.
- Handles exit codes: 0 for success, 1 for initialization errors (CLI argument parsing or zerolog configuration failures), 2 for panics, and 3 for program errors.
- All logging goes to stdout and unexpected errors go to stderr.
- On errors, a stack trace and other details from errors are shown, powered by gitlab.com/tozd/go/errors.
Installation
This is a Go package. You can add it to your project using go get:
go get gitlab.com/tozd/go/cli
It requires Go 1.21 or newer.
Usage
See full package documentation on pkg.go.dev.
See examples.
GitHub mirror
There is also a read-only GitHub mirror available, if you need to fork the project there.
Documentation
¶
Overview ¶
Package cli provides boilerplate combining Kong CLI argument parsing with zerolog logging.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( Version = "" BuildTimestamp = "" Revision = "" )
These variables should be set during build time using "-X" ldflags. They are then combined into a version string and provided as Kong variable with name "version". The variable is then used by kong.VersionFlag to show program's version. For example, to have "-v" CLI flag show program's version, your Kong config struct could be:
type App struct {
Version kong.VersionFlag `short:"V" help:"Show program's version and exit." yaml:"-"`
}
Functions ¶
func Run ¶
func Run(config hasLoggingConfig, vars kong.Vars, run func(*kong.Context) errors.E, options ...kong.Option)
Run runs the "run" function after Kong parses CLI arguments into "config" struct and zerolog logging is configured and Logger and Logger WithContext fields are set in "config" struct.
Kong vars can override zerolog defaults and add additional variables which can then be interpolated in Kong struct tags in config struct. Var named "description" is used for program's description in usage help, if provided.
Run function should always return and never call os.Exit. If it does not return an error, the program exits with code 0. If it returns an error, the program exits with code 3. The program exits with code 1 for initialization errors (CLI argument parsing or zerolog configuration failures). The program exits with code 2 on panic.
Run function should not do any output to stdout by itself, but should exclusively use the logger. Logger then uses stdout for pretty-printed or JSON logging (as configured). Any unexpected errors go to stderr and are not in any particular format nor JSON (e.g., stack traces on panic). This combines well with dinit.
Types ¶
type ConfigFlag ¶
type ConfigFlag string
ConfigFlag allows you to define a config struct passed to Kong to parse a CLI argument with the path to the config file to populate the config struct with its contents.
CLI arguments and environment variables can then override values populated by the config file.
Config file is parsed with a YAML parser so it should be in YAML or JSON. Make sure the config struct supports YAML parser to populate it (use "yaml" struct tags, implement UnmarshalYAML if custom parsing is needed, etc.).
Example:
type App struct {
Config cli.ConfigFlag `short:"c" name:"config" placeholder:"PATH" help:"Load configuration from a JSON or YAML file." yaml:"-"`
}
Source Files
Directories