kingpin

Kingpin is a fluent-style, type-safe command-line parser for Go that lets developers define flags, positional arguments, and arbitrarily nested subcommands through a chainable API. It automatically generates detailed, contextual usage help whenever —help appears anywhere on the command line, and supports POSIX-style short-flag combining, environment-variable fallbacks, default values, and reading arguments from files via @<file> expansion.

The library is commonly used to build both small single-command CLIs and large multi-command tools with git-style subcommands, similar in spirit to Cobra or Clap in other ecosystems. Kingpin v2 is now in contributions-only maintenance mode — the original author has moved on to a lighter alternative (Kong) — but the library remains stable, widely depended upon, and functionally complete for existing use cases.

What You Get

• Fluent flag/argument/command builder API with type-safe value parsing (Bool, Int, Duration, IP, ExistingFile, byte sizes, and more)
• Automatic, template-customizable usage help, long help, and man page generation
• Nested subcommands with per-command flags, positional arguments, and Action() callbacks
• Shell completion script generation for bash, zsh, and fish, plus dynamic completion support
• Support for reading arguments from files via @<file> expansion

Common Use Cases

• Building git-style CLIs with multiple subcommands and shared global flags
• Generating consistent —help and —help-man output across a large command surface
• Parsing typed flags and arguments (durations, IPs, byte sizes) without manual conversion code
• Adding shell autocompletion to an existing Go CLI tool

Under The Hood

Architecture Kingpin structures parsing around composable clause types — an Application (app.go) embeds a cmdMixin that owns a flagGroup, argGroup, and cmdGroup (model.go), while FlagClause, ArgClause, and CmdClause builders feed a tokenizing Parser (parser.go) that walks a linear Token stream (TokenShort/TokenLong/TokenArg) into a ParseContext capturing the SelectedCommand plus fully resolved values before dispatching registered Action() callbacks. This is a layered, single-responsibility flow — tokenize, resolve clauses, populate context, invoke actions — with a clean split between definition-time builder methods and parse-time state, though the coupling between Application and the internal flag/arg/cmd groups means adding a genuinely new clause kind would touch app.go, model.go, and parser.go together.

Tech Stack Kingpin is a dependency-light, pure Go library (go.mod targets an old, broadly compatible Go version) whose only non-test runtime dependencies are a byte-size parser and a human-friendly duration parser, with an additional indirect YAML dependency; tests rely on a well-known assertion library. Value parsing for its many built-in flag/argument types is code-generated via a small generator command driven by a template and a JSON type manifest, and CI runs through GitHub Actions using a pinned, vendored toolchain rather than relying on the runner’s default Go install.

Code Quality The library ships a broad set of test files covering the application, command, flag, parser, usage-rendering, and value-parsing surfaces, written against a standard assertion-style testing library rather than raw manual checks. Error handling is explicit and typed — each value’s Set method returns a wrapped parsing error instead of panicking — though a few internal invariants intentionally panic as “should never happen” guards. Naming follows conventional Go idiom throughout, and formatting/vetting are enforced implicitly via the pinned CI toolchain rather than a dedicated linter configuration.

API Design Kingpin’s defining characteristic is its fluent, chainable declaration style that reads like a sentence and yields a directly usable typed variable at definition time, paired with automatically generated and template-customizable help output and shell-completion scripts with no extra setup. These ergonomic ideas were notably ahead of their contemporaries when introduced, though the project’s own README now points newcomers toward the same author’s newer, lighter successor library, so the design is better described as an influential precedent than as cutting-edge today.