Busque em todas as páginas da documentação
O kingpin (github.com/alecthomas/kingpin/v2) modela CLIs como uma cadeia fluente: aplicação, comandos aninhados, flags tipadas, argumentos posicionais e enums validados antes que sua Action seja executada.
Ele influenciou frameworks posteriores e continua útil para ler ferramentas legadas.
O repositório upstream está arquivado; novas CLIs "greenfield" devem padronizar em cobra ou urfave/cli, mas os padrões de UX do kingpin (parsing tipado, args obrigatórios, restrições de enum) ainda se aplicam em todos os lugares.
O kingpin separa parsing de execução: você declara a gramática primeiro, depois anexa callbacks Action que recebem valores totalmente validados.
Enums restringem strings a um conjunto fixo; contadores e URLs são parseados em tipos nativos sem chamadas manuais de strconv.
UX avançada significa falhar rapidamente com mensagens precisas antes que qualquer I/O de rede ou arquivo seja executado.
Cartão de receita de referência rápida - pronto para copiar e colar.
app := kingpin.New("deploy", "CLI de deploy")
env := app.Arg("env", "ambiente de destino").Required().Enum("staging", "prod")
timeout := app.Flag("timeout", "tempo de espera").Default("30s").Duration()
kingpin.MustParse(app.Parse(os.Args[1:]))
fmt.Println(*env, *timeout)Quando usar isso:
Prefira cobra para trabalhos novos, a menos que você esteja estendendo código já construído sobre kingpin.
package main
import (
"fmt"
"os"
"time"
"github.com/alecthomas/kingpin/v2"
)
var (
app = kingpin.New("ship", "ferramenta de envio")
verbose = app.Flag("verbose", "saída detalhada").Short('v').Bool()
mode = app.Flag("mode", "modo de execução").Enum("dry", "apply")
timeout = app.Flag("timeout", "tempo limite da operação").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", "executar envio")
func run(verbose bool, mode string, timeout time.Duration) {
fmt.Printf("verbose=%v mode=%s timeout=%s\n", verbose, mode, timeout)
}O que isso demonstra:
Enum rejeita valores fora de dry e apply no momento do parse.Duration parseiam sintaxe de duração Go sem métodos Set personalizados.app.Command; FullCommand() identifica qual correspondeu.kingpin.MustParse sai em erros de gramática antes que run seja executado.Parse consome os.Args[1:], aplica padrões, executa coerção de tipo e retorna a string de comando selecionada..Required(); posicionais opcionais usam .String() sem Required.| API | Propósito |
|---|---|
.Enum("a", "b") | Restringe flag ou argumento de string |
.Required() | Falha no parse se ausente |
.Short('v') | Alias de letra única |
.Default("10s") | Padrão pré-parse para flags tipadas |
.ExistingFile() | O caminho deve existir no disco |
.URL() | Parseia e valida a forma da URL |
| kingpin | equivalente cobra |
|---|---|
app.Flag(...).Bool() | cmd.Flags().BoolVar |
app.Arg(...).Required() | Args: cobra.ExactArgs(1) + RunE |
.Enum(...) | validação personalizada em PreRunE ou MarkFlagRequired + verificação de conjunto permitido |
app.Command("run", ...) | &cobra.Command{Use: "run"} |
cmd, não em bibliotecas.MustParse, a lógica de negócios deve residir em funções simples para testabilidade.os/exec.app tornam o teste sensível à ordem. Correção: envolva parse + ação em funções que aceitam []string.os.Args. Correção: um framework por binário.| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| cobra | Novas ferramentas, ecossistema k8s | Você apenas mantém kingpin legado |
| urfave/cli v2 | Estrutura de app baseada em hooks | Você precisa de scaffolds do kubebuilder |
| kong | Tags de struct controlam a CLI | A equipe já conhece kingpin |
| stdlib flag | Apenas duas flags | Validação de enum é manual |
Prefira cobra ou urfave/cli para código novo.
kingpin é apropriado quando você estende um binário existente já escrito com ele.
Enums do kingpin são declarados no momento da construção da gramática e validam antes que as ações rodem.
flag.Value valida por flag na stdlib com mais boilerplate.
O suporte é limitado em comparação com cobra.
Planeje scripts de completion manuais ou migre se o completion por tab for crítico.
Chame app.Parse([]string{"run", "--mode=dry"}) sem tocar em os.Args, ou teste a função run após o parse com valores injetados.
Valide na Action após o parse ou migre para MarkFlagsMutuallyExclusive do cobra (recursos pflag do Go 1.22+).
Documente conflitos claramente no texto de ajuda.
Cada Command obtém sua própria seção de ajuda gerada a partir das definições fluentes.
Mantenha as strings Help orientadas para ação ("executar envio", não "comando de execução").
Sim para CLIs Go; usuários do PowerShell ainda esperam flags longas em scripts.
Documente formas portáteis nos exemplos do README.
.ExistingFile() e .ExistingDir() verificam os caminhos no disco durante o parse.
Falhe rapidamente antes de uploads lentos quando os caminhos estiverem errados.
Não.
Mantenha a gramática da CLI em pacotes main ou cmd para que os consumidores da biblioteca não sejam forçados a um framework de CLI.
Validar cedo, flags tipadas, enums explícitos e argumentos obrigatórios mapeiam diretamente para PreRunE do cobra e validadores de flag.
Trate o código kingpin como uma especificação ao reescrever comandos.
Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 19 de jul. de 2026