# alecthomas/kingpin: a contributions-only Go flag and command parser

> Kingpin is a fluent, type-safe command-line parser for Go with nested commands, positional arguments and template-driven help. It is feature stable, and the README states that fixes only arrive through pull requests.

**alecthomas/kingpin** — CONTRIBUTIONS ONLY: A Go (golang) command line and flag parser

- Repository: https://github.com/alecthomas/kingpin
- Stars: 3,567 · Forks: 280
- Language: Go
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/alecthomas-kingpin

## What kingpin solves, and who it is for

Go's standard flag package handles flat flags. It does not give you nested subcommands, required positional arguments, or a help page that adapts to where the user is in the command tree. Kingpin fills that gap with a fluent builder API: you declare flags, arguments and commands as package-level values, and it parses os.Args against them. The README describes it as a "fluent-style, type-safe command-line parser" that "supports flags, nested commands, and positional arguments".

The audience is Go developers building a tool with more than a handful of options, especially one with subcommands such as a client that talks to a server. The README's own example is a chat client with a post command. If your program takes two flags and no subcommands, the standard library is enough and kingpin adds a dependency for no gain.

## How the fluent API and parser fit together

The mechanism is declaration followed by a single parse call. You build a model at package scope with kingpin.Flag, kingpin.Arg and kingpin.Command, each returning a clause you can chain methods onto: Short, Required, Bool, Int, String, Default, Action. The returned pointers are populated during kingpin.Parse().

The README gives this shape:

```go
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)
}
```

Two user-visible changes separate v2 from v1, both documented in the README. Flags can now appear at any point after their definition rather than immediately after their command, and a short flag can be combined with its parameter, so -aparm is accepted where -a parm was previously required. The repository layout separates the moving parts: parser.go, model.go, flags.go, args.go, cmd.go, usage.go and the template files templates.go and usage_template.go. Parsing and help rendering are distinct code paths, which is why the help output can be replaced without touching the parser.

## Installing kingpin/v2 and running a first command

The README gives one installation line for the current stable version. It fetches the module into your Go module cache; the go.mod in the repository declares module github.com/alecthomas/kingpin/v2 with go 1.17.

```bash
go get github.com/alecthomas/kingpin/v2
```

The README also documents the deprecated v1 path, go get gopkg.in/alecthomas/kingpin.v1, and states that v1 is in maintenance mode. New code should use the v2 import path.

For a first real use, take the README's own two-value example and run it. With the declarations above in place, calling the binary with -v and a name prints the boolean and the string. The README notes that kingpin tries to give "detailed contextual help if --help is encountered at any point in the command line (excluding after --)". Two hidden flags, --help-long and --help-man, are listed in the change history, and the feature list mentions automatic man page generation via --help-man. Shell completion for Bash, ZSH and Fish is covered by a section of the README, and there is a completions.go file in the repository.

## Where kingpin stops being the right tool

The largest limitation is not technical. The README opens with a CONTRIBUTIONS ONLY notice: "I do not have time to fix issues myself. The only way fixes or new features will be added is by people submitting PRs." The author states he no longer uses kingpin personally and now uses kong. The same notice says kingpin is "largely feature stable" and that "there are some bugs that should be fixed". So a bug you hit may sit until someone writes the patch. The last push to master was on 2026-09-14, but the most recent tagged release, v2.4.0, dates from 2023-11-16, which means the release cadence is far slower than the commit activity suggests.

On the technical side, the fluent style means your command definitions are Go code evaluated at package init, not data. There is no struct-tag mapping, no config file format, and no reflection over a struct to derive flags; you write each clause by hand. That is more verbose than a tag-based parser for large command trees. The README does not document rollback behaviour or a migration path if you later leave kingpin, and it does not state a support window for v1 beyond calling it deprecated and in maintenance mode.

## kingpin against kong, by the same author

The README names kong directly: the author says he now uses github.com/alecthomas/kong instead of kingpin. That makes kong the natural alternative to weigh, and the difference in approach is structural. Kingpin builds a parser model imperatively through chained calls on Flag, Arg and Command. Kong, as described in the kingpin README's framing, is the parser the author moved to, and the two projects share an author but not an API style. If you want your CLI definition to look like a struct with tags, kong is the direction the author himself took; if you want explicit builder calls and a template you can override, kingpin is the one with the documented UsageTemplate and CompactUsageTemplate hooks.

The README also lists two included templates, DefaultUsageTemplate and CompactUsageTemplate, the latter described as a compact command template for larger applications. Custom help is a first-class feature here, exposed through Go templates, and that is the part of kingpin that is hardest to replace with a smaller library.

## Maintenance cost, version pinning and the MIT licence

The upgrade surface is small. The repository's go.mod depends on github.com/alecthomas/units, github.com/xhit/go-str2duration/v2 and, for tests, github.com/stretchr/testify. Those are the transitive pieces you inherit. The module declares go 1.17, so it will build on any toolchain at or above that line.

Because the README says the project is feature stable and contributions only, the realistic maintenance cost is not chasing new releases; it is deciding whether to carry a patch yourself if a bug affects you. The release history shows v2.4.0 in 2023 and v1.3.4 back in 2015, so major version churn is not a concern.

The project is MIT licensed, with a COPYING file at the repository root. MIT is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are retained. That is a description of the licence text, not legal advice; if your organisation has licence review rules, run the COPYING file past whoever owns that process. Nothing in the README suggests a contributor licence agreement or a change of licence for v2.

## Conclusion

Adopt kingpin/v2 if you already depend on it or you want typed flags, nested commands and Go-template help without writing a parser, and you accept that fixes arrive through pull requests rather than from the maintainer, who states he no longer uses the project. Do not adopt it expecting a roadmap: the README says it is feature stable and that new features come only from contributors. Before committing, read the CONTRIBUTIONS ONLY notice at the top of the README, confirm the v2.4.0 tag is the version you are pinning, and check whether the specific bug you care about has an open pull request. kong, by the same author, is the parser he uses now, and choosing between them is a question of whether you want struct tags instead of fluent calls.

## FAQ

### How do I install alecthomas/kingpin?

The README gives the command go get github.com/alecthomas/kingpin/v2 for the current stable version. The older v1 path, go get gopkg.in/alecthomas/kingpin.v1, is documented as deprecated and in maintenance mode.

### How do I use alecthomas/kingpin in a Go program?

You declare flags, arguments and commands with kingpin.Flag, kingpin.Arg and kingpin.Command, then call kingpin.Parse() in main and read the returned pointers. The README's example declares a verbose Bool flag with Short('v') and a required String argument named name.

### Is alecthomas/kingpin still maintained?

The README carries a CONTRIBUTIONS ONLY notice stating that the author does not have time to fix issues himself and that fixes or new features arrive only through pull requests. It also says kingpin is largely feature stable, with some bugs that should be fixed.

### What changed between kingpin v1 and v2?

The README lists user-visible changes: flags can be used at any point after their definition, and short flags can be combined with their parameters. On the API side, ParseWithFileExpansion() is gone, Dispatch() was renamed to Action(), and ParseContext(), Terminate(), UsageTemplate() and FatalUsage() were added.

### Can alecthomas/kingpin generate shell completion and man pages?

The README has a section on Bash, ZSH and Fish shell completion, and the feature list mentions automatic man page generation through --help-man. The --help-man and --help-long flags are described in the change history as hidden by default.

### What licence does alecthomas/kingpin use?

The repository is MIT licensed and carries a COPYING file at its root. MIT permits use, modification and redistribution as long as the copyright and permission notices are kept.

## Sources

- [alecthomas/kingpin on GitHub](https://github.com/alecthomas/kingpin)
- [Issues](https://github.com/alecthomas/kingpin/issues)
- [License: MIT](https://github.com/alecthomas/kingpin/blob/master/LICENSE)
- [README](https://github.com/alecthomas/kingpin/blob/master/README.md)
- [Releases](https://github.com/alecthomas/kingpin/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alecthomas-kingpin