CONTRIBUTIONS ONLY

What does this mean? I do not have time to fix issues myself. The only way fixes or new features will be added is by people submitting PRs. If you are interested in taking over maintenance and have a history of contributions to Kingpin, please let me know.

Current status. Kingpin is largely feature stable. There hasn't been a need to add new features in a while, but there are some bugs that should be fixed.

Why? I no longer use Kingpin personally (I now use kong). Rather than leave the project in a limbo of people filing issues and wondering why they're not being worked on, I believe this notice will more clearly set expectations.

Kingpin - A Go (golang) command line and flag parser

• Overview
• Features
• User-visible changes between v1 and v2
• Flags can be used at any point after their definition.
• Short flags can be combined with their parameters
• API changes between v1 and v2
• Versions
• V2 is the current stable version
• V1 is the OLD stable version
• Change History
• Examples
• Simple Example
• Complex Example
• Reference Documentation
• Displaying errors and usage information
• Sub-commands
• Custom Parsers
• Repeatable flags
• Boolean Values
• Default Values
• Place-holders in Help
• Consuming all remaining arguments
• Bash/ZSH Shell Completion
• Supporting -h for help
• Custom help

Overview

Kingpin is a fluent-style, type-safe command-line parser. It supports flags, nested commands, and positional arguments.

Install it with:

$ go get github.com/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 --).

Features

• Help output that isn't as ugly as sin.
• Fully customisable help, via Go templates.
• Parsed, type-safe flags (kingpin.Flag("f", "help").Int())
• Parsed, type-safe positional arguments (kingpin.Arg("a", "help").Int()).
• Parsed, type-safe, arbitrarily deep commands (kingpin.Command("c", "help")).
• Support for required flags and required positional arguments (kingpin.Flag("f", "").Required().Int()).
• Support for arbitrarily nested default commands (command.Default()).
• Callbacks per command, flag and argument (kingpin.Command("c", "").Action(myAction)).
• POSIX-style short flag combining (-a -b -> -ab).
• Short-flag+parameter combining (-a parm -> -aparm).
• Read command-line from files (@<file>).
• Automatically generate man pages (--help-man).

User-visible changes between v1 and v2

Flags can be used at any point after their definition.

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

Short flags can be combined with their parameters

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.

API changes between v1 and v2

• ParseWithFileExpansion() is gone. The new parser directly supports expanding @<file>.
• Added FatalUsage() and FatalUsageContext() for displaying an error + usage and terminating.
• Dispatch() renamed to Action().
• Added ParseContext() for parsing a command line into its intermediate context form without executing.
• Added Terminate() function to override the termination function.
• Added UsageForContextWithTemplate() for printing usage via a custom template.
• Added UsageTemplate() for overriding the default template to use. Two templates are included:
  1. DefaultUsageTemplate - default template.
  2. CompactUsageTemplate - compact command template for larger applications.

Versions

The current stable version is github.com/alecthomas/kingpin/v2. The previous version, gopkg.in/alecthomas/kingpin.v1, is deprecated and in maintenance mode.

V2 is the current stable version

Installation:

$ go get github.com/alecthomas/kingpin/v2

V1 is the OLD stable version

Installation:

$ go get gopkg.in/alecthomas/kingpin.v1

Change History

• 2015-09-19 -- Stable v2.1.0 release.

  • Added command.Default() to specify a default command to use if no other command matches. This allows for convenient user shortcuts.
  • Exposed 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.
  • Flags are "interspersed" by default, but can be disabled with app.Interspersed(false).
  • Added flags for all simple builtin types (int8, uint16, etc.) and slice variants.
  • Use app.Writer(os.Writer) to specify the default writer for all output functions.
  • Dropped os.Writer prefix from all printf-like functions.

• 2015-05-22 -- Stable v2.0.0 release.

  • Initial stable release of v2.0.0.
  • Fully supports interspersed flags, commands and arguments.
  • Flags can be present at any point after their logical definition.
  • Application.Parse() terminates if commands are present and a command is not parsed.
  • Dispatch() -> Action().
  • Actions are dispatched after all values are populated.
  • Override termination function (defaults to os.Exit).
  • Override output stream (defaults to os.Stderr).
  • Templatised usage help, with default and compact templates.
  • Make error/usage functions more consistent.
  • Support argument expansion from files by default (with @).
  • Fully public data model is available via .Model().
  • Parser has been completely refactored.
  • Parsing and execution has been split into distinct stages.
  • Use go generate to generate repeated flags.
  • Support combined short-flag+argument: -fARG.

• 2015-01-23 -- Stable v1.3.4 release.

  • Support "--" for separating flags from positional arguments.
  • Support loading flags from files (ParseWithFileExpansion()). Use @FILE as an argument.
  • Add post-app and post-cmd validation hooks. This allows arbitrary validation to be added.
  • A bunch of improvements to help usage and formatting.
  • Support arbitrarily nested sub-commands.

• 2014-07-08 -- Stable v1.2.0 release.

  • Pass any value through to Strings() when final argument. Allows for values that look like flags to be processed.
  • Allow --help to be used with commands.
  • Support Hidden() flags.
  • Parser for units.Base2Bytes type. Allows for flags like --ram=512MB or --ram=1GB.
  • Add an 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.

  • Bug fixes.
  • Always return an error (rather than panicing) when misconfigured.
  • OpenFile(flag, perm) value type added, for finer control over opening files.
  • Significantly improved usage formatting.

• 2014-06-19 -- Stable v1.0.0 release.

  • Support cumulative positional arguments.
  • Return error rather than panic when there are fatal errors not caught by the type system. eg. when a default value is invalid.
  • Use gokpg.in.

• 2014-06-10 -- Place-holder streamlining.

  • Renamed MetaVar to PlaceHolder.
  • Removed MetaVarFromDefault. Kingpin now uses heuristics to determine what to display.

Examples

Simple Example

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 5

From the following source:

package main

import (
  "fmt"

  "github.com/alecthomas/kingpin/v2"
)

var (
  debug   = kingpin.Flag("debug", "Enable debug mode.").Bool()
  timeout = kingpin.Flag("timeout", "Timeout waiting for ping.").Default("5s").Envar("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\n", *ip, *timeout, *count)
}

Reading arguments from a file

Kingpin supports reading arguments from a file. Create a file with the corresponding arguments:

echo -t=5\n > args

And now supply it:

$ ping @args

Complex Example

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"
  "github.com/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)
  }
}

Reference Documentation

Displaying errors and usage information

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:

There are equivalent global functions in the kingpin namespace for the default kingpin.CommandLine instance.

Sub-commands

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:

```go var ( deleteCommand = kingpin.Command("delete", "Delete an object.") deleteUserCommand = deleteCommand.Command("user", "Delete a user.") deleteUserUIDFlag =