kingpin & Advanced CLI UX

kingpin (github.com/alecthomas/kingpin/v2) models CLIs as a fluent chain: application, nested commands, typed flags, positional arguments, and enums validated before your Action runs.

It influenced later frameworks and remains useful for reading legacy tools.

The upstream repository is archived; new greenfield CLIs should standardize on cobra or urfave/cli, but kingpin's UX patterns (typed parsing, required args, enum constraints) still apply everywhere.

Summary

kingpin separates parsing from execution: you declare the grammar first, then attach Action callbacks that receive fully validated values.

Enums restrict strings to a fixed set; counters and URLs parse into native types without manual strconv calls.

Advanced UX means failing fast with precise messages before any network or file I/O runs.

Recipe

Quick-reference recipe card - copy-paste ready.

app := kingpin.New("deploy", "deploy CLI")
env := app.Arg("env", "target environment").Required().Enum("staging", "prod")
timeout := app.Flag("timeout", "wait").Default("30s").Duration()
kingpin.MustParse(app.Parse(os.Args[1:]))
fmt.Println(*env, *timeout)

When to reach for this:

• Maintaining an existing kingpin-based binary (legacy internal tools).
• Studying fluent CLI grammars with enum and type validation.
• Prototyping strict arg validation before committing to cobra.

Prefer cobra for new work unless you are extending code already built on kingpin.

Working Example

package main
 
import (
    "fmt"
    "os"
    "time"
 
    "github.com/alecthomas/kingpin/v2"
)
 
var (
    app     = kingpin.New("ship", "shipping tool")
    verbose = app.Flag("verbose", "verbose output").Short('v').Bool()
    mode    = app.Flag("mode", "run mode").Enum("dry", "apply")
    timeout = app.Flag("timeout", "operation timeout").Default("10s").Duration()
)
 
func main() {
    cmd := kingpin.MustParse(app.Parse(os.Args[1:]))
    switch cmd {
    case shipRun.FullCommand():
        run(*verbose, *mode, *timeout)
    }
}
 
var shipRun = app.Command("run", "execute shipment")
 
func run(verbose bool, mode string, timeout time.Duration) {
    fmt.Printf("verbose=%v mode=%s timeout=%s\n", verbose, mode, timeout)
}

What this demonstrates:

• Enum rejects values outside dry and apply at parse time.
• Duration flags parse Go duration syntax without custom Set methods.
• Subcommands are app.Command nodes; FullCommand() identifies which matched.
• kingpin.MustParse exits on grammar errors before run executes.

Deep Dive

How It Works

• kingpin builds a parse tree at package init (typical pattern uses package-level vars).
• Parse consumes os.Args[1:], applies defaults, runs type coercion, and returns the selected command string.
• Required args use .Required(); optional positionals use .String() without Required.
• Help and version templates are customizable like other frameworks.

Validation Features at a Glance

Migration to cobra

Go Notes

• Package-level kingpin vars run at init; keep declarations in cmd packages, not libraries.
• After MustParse, business logic should live in plain functions for testability.
• If migrating, port one subcommand at a time behind integration tests using os/exec.

Gotchas

• Archived upstream - Security fixes may lag; plan migration for externally distributed tools. Fix: track cobra parity issues in a ticket and freeze new kingpin commands.
• Init-order coupling - Global app vars make testing order-sensitive. Fix: wrap parse + action in functions accepting []string.
• Enum on unset flag - Required enums must have defaults or be required flags. Fix: document valid values in help strings.
• Mixing kingpin and stdlib flag - Two parsers fight over os.Args. Fix: one framework per binary.
• Over-nesting commands - Deep trees harm discoverability. Fix: flatten verbs or add topic-based groups in help.

Alternatives

FAQs

Related

• cobra & urfave/cli Command Trees - recommended modern tree
• flag Package & POSIX-Style Flags - stdlib baseline
• Color Output & User-Friendly Errors - parse error presentation
• CLI Tools Basics - manual validation patterns
• CLI Tools Best Practices - testing and migration hygiene

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).