gopkg.in/alecthomas/kingpin.v3-unstable
Kingpin is a fluent-style, type-safe command-line parser. It supports flags, nested commands, and positional arguments.
Install it with:
$ go get gopkg.in/alecthomas/kingpin.v2
It looks like this:
var (
verbose = kingpin.Flag("verbose", "Verbose mode.").Short('v').Bool()
name = kingpin.Arg("name", "Name of user.").Required().String()
)
func main() {
kingpin.Parse()
fmt.Printf("%v, %s\n", *verbose, *name)
}
More examples are available.
Second to parsing, providing the user with useful help is probably the most
important thing a command-line parser does. Kingpin tries to provide detailed
contextual help if --help is encountered at any point in the command line
(excluding after --).
kingpin.Flag("f", "help").Int())kingpin.Arg("a", "help").Int()).kingpin.Command("c", "help")).kingpin.Flag("f", "").Required().Int()).command.Default()).kingpin.Command("c", "").Action(myAction)).-a -b -> -ab).-a parm -> -aparm).@<file>).--help-man).--[no-]flag).Some flag types had unintended side-effects, or poor usability. For example, flags that created/opened files could result in file-descriptor leaks. To avoid confusion these have been removed.
Bool() now creates a non-negatable flag.
Use NegatableBool() to add a boolean flag that supports both --flag and
--no-flag. This will be displayed in the help.
Flags can be specified at any point after their definition, not just immediately after their associated command. From the chat example below, the following used to be required:
$ chat --server=chat.server.com:8080 post --image=~/Downloads/owls.jpg pics
But the following will now work:
$ chat post --server=chat.server.com:8080 --image=~/Downloads/owls.jpg pics
Previously, if a short flag was used, any argument to that flag would have to be separated by a space. That is no longer the case.
ParseWithFileExpansion() is gone. The new parser directly supports expanding @<file>.FatalUsage() and FatalUsageContext() for displaying an error + usage and terminating.Dispatch() renamed to Action().ParseContext() for parsing a command line into its intermediate context form without executing.Terminate() function to override the termination function.UsageForContextWithTemplate() for printing usage via a custom template.UsageTemplate() for overriding the default template to use. Two templates are included:
DefaultUsageTemplate - default template.CompactUsageTemplate - compact command template for larger applications.Kingpin uses gopkg.in for versioning.
The current stable version is gopkg.in/alecthomas/kingpin.v2. The previous version, gopkg.in/alecthomas/kingpin.v1, is deprecated and in maintenance mode.
Installation:
$ go get gopkg.in/alecthomas/kingpin.v2
Installation:
$ go get gopkg.in/alecthomas/kingpin.v1
2015-09-19 -- Stable v2.1.0 release.
command.Default() to specify a default command to use if no other
command matches. This allows for convenient user shortcuts.HelpFlag and VersionFlag for further customisation.Action() and PreAction() added and both now support an arbitrary
number of callbacks.kingpin.SeparateOptionalFlagsUsageTemplate.--help-long and --help-man (hidden by default) flags.app.Interspersed(false).app.Writer(os.Writer) to specify the default writer for all output functions.os.Writer prefix from all printf-like functions.2015-05-22 -- Stable v2.0.0 release.
go generate to generate repeated flags.2015-01-23 -- Stable v1.3.4 release.
2014-07-08 -- Stable v1.2.0 release.
Strings() when final argument.
Allows for values that look like flags to be processed.--help to be used with commands.Hidden() flags.--ram=512MB or --ram=1GB.Enum() value, allowing only one of a set of values
to be selected. eg. Flag(...).Enum("debug", "info", "warning").2014-06-27 -- Stable v1.1.0 release.
OpenFile(flag, perm) value type added, for finer control over opening files.2014-06-19 -- Stable v1.0.0 release.
2014-06-10 -- Place-holder streamlining.
MetaVar to PlaceHolder.MetaVarFromDefault. Kingpin now uses heuristics
to determine what to display.Kingpin can be used for simple flag+arg applications like so:
$ ping --help
usage: ping [<flags>] <ip> [<count>]
Flags:
--debug Enable debug mode.
--help Show help.
-t, --timeout=5s Timeout waiting for ping.
Args:
<ip> IP address to ping.
[<count>] Number of packets to send
$ ping 1.2.3.4 5
Would ping: 1.2.3.4 with timeout 5s and count 0
From the following source:
package main
import (
"fmt"
"gopkg.in/alecthomas/kingpin.v2"
)
var (
debug = kingpin.Flag("debug", "Enable debug mode.").Bool()
timeout = kingpin.Flag("timeout", "Timeout waiting for ping.").Default("5s").OverrideDefaultFromEnvar("PING_TIMEOUT").Short('t').Duration()
ip = kingpin.Arg("ip", "IP address to ping.").Required().IP()
count = kingpin.Arg("count", "Number of packets to send").Int()
)
func main() {
kingpin.Version("0.0.1")
kingpin.Parse()
fmt.Printf("Would ping: %s with timeout %s and count %d", *ip, *timeout, *count)
}
Kingpin can also produce complex command-line applications with global flags, subcommands, and per-subcommand flags, like this:
$ chat --help
usage: chat [<flags>] <command> [<flags>] [<args> ...]
A command-line chat application.
Flags:
--help Show help.
--debug Enable debug mode.
--server=127.0.0.1 Server address.
Commands:
help [<command>]
Show help for a command.
register <nick> <name>
Register a new user.
post [<flags>] <channel> [<text>]
Post a message to a channel.
$ chat help post
usage: chat [<flags>] post [<flags>] <channel> [<text>]
Post a message to a channel.
Flags:
--image=IMAGE Image to post.
Args:
<channel> Channel to post to.
[<text>] Text to post.
$ chat post --image=~/Downloads/owls.jpg pics
...
From this code:
package main
import (
"os"
"strings"
"gopkg.in/alecthomas/kingpin.v2"
)
var (
app = kingpin.New("chat", "A command-line chat application.")
debug = app.Flag("debug", "Enable debug mode.").Bool()
serverIP = app.Flag("server", "Server address.").Default("127.0.0.1").IP()
register = app.Command("register", "Register a new user.")
registerNick = register.Arg("nick", "Nickname for user.").Required().String()
registerName = register.Arg("name", "Name of user.").Required().String()
post = app.Command("post", "Post a message to a channel.")
postImage = post.Flag("image", "Image to post.").File()
postChannel = post.Arg("channel", "Channel to post to.").Required().String()
postText = post.Arg("text", "Text to post.").Strings()
)
func main() {
switch kingpin.MustParse(app.Parse(os.Args[1:])) {
// Register user
case register.FullCommand():
println(*registerNick)
// Post message
case post.FullCommand():
if *postImage != nil {
}
text := strings.Join(*postText, " ")
println("Post:", text)
}
}
Kingpin exports a set of functions to provide consistent errors and usage information to the user.
Error messages look something like this:
<app>: error: <message>
The functions on Application are:
| Function | Purpose |
|---|---|
Errorf(format, args) | Display a printf formatted error to the user. |
Fatalf(format, args) | As with Errorf, but also call the termination handler. |
FatalUsage(format, args) | As with Fatalf, but also print contextual usage information. |
FatalUsageContext(context, format, args) | As with Fatalf, but also print contextual usage information from a ParseContext. |
FatalIfError(err, format, args) | Conditionally print an error prefixed with format+args, then call the termination handler |
There are equivalent global functions in the kingpin namespace for the default
kingpin.CommandLine instance.
Kingpin supports nested sub-commands, with separate flag and positional arguments per sub-command. Note that positional arguments may only occur after sub-commands.
For example:
var (
deleteCommand = kingpin.Command("delete", "Delete an object.")
deleteUserCommand = deleteCommand.Command("user", "Delete a user.")
deleteUserUIDFlag = deleteUserCommand.Flag("uid", "Delete user by UID rather than username.")
deleteUserUsername = deleteUserCommand.Arg("username", "Username to delete.")
deletePostCommand = deleteCommand.Command("post", "Delete a post.")
)
func main() {
switch kingpin.Parse() {
case "delete user":
case "delete post":
}
}
Kingpin supports both flag and positional argument parsers for converting to
Go types. For example, some included parsers are Int(), Float(),
Duration() and ExistingFile().
Parsers conform to Go's flag.Value
interface, so any existing implementations will work.
For example, a parser for accumulating HTTP header values might look like this:
type HTTPHeaderValue http.Header
func (h *HTTPHeaderValue) Set(value string) error {
parts := strings.SplitN(value, ":", 2)
if len(parts) != 2 {
return fmt.Errorf("expected HEADER:VALUE got '%s'", value)
}
(*http.Header)(h).Add(parts[0], parts[1])
return nil
}
func (h *HTTPHeaderValue) String() string {
return ""
}
As a convenience, I would recommend something like this:
func HTTPHeader(s Settings) (target *http.Header) {
target = &http.Header{}
s.SetValue((*HTTPHeaderValue)(target))
return
}
You would use it like so:
headers = HTTPHeader(kingpin.Flag("header", "Add a HTTP header to the request.").Short('H'))
Depending on the Value they hold, some flags may be repeated. The
IsCumulative() bool function on Value tells if it's safe to call Set()
multiple times or if an error should be raised if several values are passed.
The built-in Values returning slices and maps, as well as Counter are
examples of Values that make a flag repeatable.
Boolean values are uniquely managed by Kingpin. Each boolean flag will have a negative complement:
--<name> and --no-<name>.
The default value is the zero value for a type. This can be overridden with
the Default(value...) function on flags and arguments. This function accepts
one or several strings, which are parsed by the value itself, so they must
be compliant with the format expected.
The place-holder value for a flag is the value used in the help to describe the value of a non-boolean flag.
The value provided to PlaceHolder() is used if provided, then the value provided by Default() if provided, then finally the capitalised flag name is used.
Here are some examples of flags with various permutations:
--name=NAME // Flag(...).String()
--name="Harry" // Flag(...).Default("Harry").String()
--name=FULL-NAME // flag(...).PlaceHolder("FULL-NAME").Default("Harry").String()
A common command-line idiom is to use all remaining arguments for some purpose. eg. The following command accepts an arbitrary number of IP addresses as positional arguments:
./cmd ping 10.1.1.1 192.168.1.1
Such arguments are similar to repeatable flags, but for
arguments. Therefore they use the same IsCumulative() bool function on the
underlying Value, so the built-in Values for which the Set() function
can be called several times will consume multiple arguments.
To implement the above example with a custom Value, we might do something
like this:
type ipList []net.IP
func (i *ipList) Set(value string) error {
if ip := net.ParseIP(value); ip == nil {
return fmt.Errorf("'%s' is not an IP address", value)
} else {
*i = append(*i, ip)
return nil
}
}
func (i *ipList) String() string {
return ""
}
func (i *ipList) IsCumulative() bool {
return true
}
func IPList(s Settings) (target *[]net.IP) {
target = new([]net.IP)
s.SetValue((*ipList)(target))
return
}
And use it like so:
ips := IPList(kingpin.Arg("ips", "IP addresses to ping."))
Kingpin v3 now supports custom value resolvers for flags and arguments. This is used internally to resolve default values and environment variables, but applications can define their own resolvers to load flags from configuration files, or elsewhere.
Included is a JSONResolver that loads values from a JSON file, including multi-value flags.
Kingpin v3 now supports defining flags, arguments and commands via struct reflection. If desired, this can (almost) completely replace the fluent-style interface.
The name of the flag will default to the CamelCase name transformed to camel- case. This can be overridden with the "long" tag.
All basic Go types are supported including floats, ints, strings, time.Duration, and slices of same.
For compatibility, also supports the tags used by https://github.com/jessevdk/go-flags
type MyFlags struct {
Arg string `arg:"true" help:"An argument"`
Debug bool `help:"Enable debug mode."`
URL string `help:"URL to connect to." default:"localhost:80"`
Login struct {
Name string `help:"Username to authenticate with." args:"true"`
} `help:"Login to server."`
}
flags := &MyFlags{}
kingpin.Struct(flags)
Supported struct tags are:
| Tag | Description |
|---|---|
help | Help text. |
placeholder | Placeholder text. |
default | Default value. |
short | Short name, if flag. |
long | Long name, for overriding field name. |
required | If present, flag/arg is required. |
hidden | If present, flag/arg/command is hidden. |
enum | For enums, a comma separated list of cases. |
arg | If true, field is an argument. |
By default, all flags and commands/subcommands generate completions internally.
Out of the box, CLI tools using kingpin should be able to take advantage
of completion hinting for flags and commands. By specifying
--completion-bash as the first argument, your CLI tool will show
possible subcommands. By ending your argv with --, hints for flags
will be shown.
To allow your end users to take advantage you must package a
/etc/bash_completion.d script with your distribution (or the equivalent
for your target platform/shell). An alternative is to instruct your end
user to source a script from their bash_profile (or equivalent).
Fortunately Kingpin makes it easy to generate or source a script for use
with end users shells. ./yourtool --completion-script-bash and
./yourtool --completion-script-zsh will generate these scripts for you.
Installation by Package
For the best user experience, you should bundle your pre-created
completion script with your CLI tool and install it inside
/etc/bash_completion.d (or equivalent). A good suggestion is to add
this as an automated step to your build pipeline, in the implementation
is improved for bug fixed.
Installation by bash_profile
Alternatively, instruct your users to add an additional statement to
their bash_profile (or equivalent):
eval "$(your-cli-tool --completion-script-bash)"
Or for ZSH
eval "$(your-cli-tool --completion-script-zsh)"
To provide more flexibility, a completion option API has been exposed for flags to allow user defined completion options, to extend completions further than just EnumVar/Enum.
Provide Static Options
When using an Enum or EnumVar, users are limited to only the options
given. Maybe we wish to hint possible options to the user, but also
allow them to provide their own custom option. HintOptions gives
this functionality to flags.
app := kingpin.New("completion", "My application with bash completion.")
app.Flag("port", "Provide a port to connect to").
Required().
HintOptions("80", "443", "8080").
IntVar(&c.port)
Provide Dynamic Options
Consider the case that you needed to read a local database or a file to provide suggestions. You can dynamically generate the options
func listHosts(args []string) []string {
// Provide a dynamic list of hosts from a hosts file or otherwise
// for bash completion. In this example we simply return static slice.
// You could use this functionality to reach into a hosts file to provide
// completion for a list of known hosts.
return []string{"sshhost.example", "webhost.example", "ftphost.example"}
}
app := kingpin.New("completion", "My application with bash completion.")
app.Flag("flag-1", "").HintAction(listHosts).String()
EnumVar/Enum
When using Enum or EnumVar, any provided options will be automatically
used for bash autocompletion. However, if you wish to provide a subset or
different options, you can use HintOptions or HintAction which will override
the default completion options for Enum/EnumVar.
Examples
You can see an in depth example of the completion API within
examples/completion/main.go
kingpin.CommandLine.GetFlag("help").Short('h')
Kingpin supports templatised help using the text/template library.
You can specify the template to use with the Application.UsageTemplate() function.
There are four included templates: kingpin.DefaultUsageTemplate is the
default, kingpin.CompactUsageTemplate provides a more compact representation
for more complex command-line structures, and kingpin.ManPageTemplate is
used to generate man pages.
See the above templates for examples of usage, and the the function UsageForContextWithTemplate() method for details on the context.
It is often useful to add extra help formats, such as man pages, etc. Here's how you'd add a --help-man flag:
kingpin.Flag("help-man", "Generate man page.").
UsageActionTemplate(kingpin.ManPageTemplate).
Bool()
$ go run ./examples/curl/curl.go --help
usage: curl [<flags>] <command> [<args> ...]
An example implementation of curl.
Flags:
--help Show help.
-t, --timeout=5s Set connection timeout.
-H, --headers=HEADER=VALUE
Add HTTP headers to the request.
Commands:
help [<command>...]
Show help.
get url <url>
Retrieve a URL.
get file <file>
Retrieve a file.
post [<flags>] <url>
POST a resource.
$ go run ./examples/curl/curl.go --help
usage: curl [<flags>] <command> [<args> ...]
An example implementation of curl.
Flags:
--help Show help.
-t, --timeout=5s Set connection timeout.
-H, --headers=HEADER=VALUE
Add HTTP headers to the request.
Commands:
help [<command>...]
get [<flags>]
url <url>
file <file>
post [<flags>] <url>
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.