kingpin & UX avanzada de CLI

Q: ¿Cómo pruebo los comandos de kingpin?

Llama a app.Parse([]string{"run", "--mode=dry"}) sin tocar os.Args, o prueba la función run después del parseo con valores inyectados.

Q: ¿Qué pasa con los flags mutuamente excluyentes requeridos?

Valida en la Action después del parseo o migra a cobra MarkFlagsMutuallyExclusive (características de pflag en Go 1.22+). Documenta los conflictos claramente en el texto de ayuda.

Q: ¿Cómo maneja kingpin la ayuda de subcomandos?

Cada Command obtiene su propia sección de ayuda generada a partir de las definiciones fluidas. Mantén las cadenas Help orientadas a la acción ("ejecutar envío", no "comando de ejecución").

Q: ¿Cómo funcionan los validadores de archivos?

.ExistingFile() y .ExistingDir() hacen stat de las rutas durante el parseo. Falla rápido antes de subidas lentas cuando las rutas son incorrectas.

Q: ¿Deberían las bibliotecas importar kingpin?

No. Mantén la gramática de la CLI en los paquetes main o cmd para que los consumidores de la biblioteca no se vean obligados a usar un framework de CLI.

kingpin (github.com/alecthomas/kingpin/v2) modela las CLIs como una cadena fluida: aplicación, comandos anidados, flags tipados, argumentos posicionales y enums validados antes de que se ejecute tu Action.

Influyó en frameworks posteriores y sigue siendo útil para leer herramientas heredadas.

El repositorio original está archivado; las nuevas CLIs desde cero deberían estandarizarse en cobra o urfave/cli, pero los patrones de UX de kingpin (parseo tipado, argumentos requeridos, restricciones de enum) siguen aplicándose en todas partes.

Resumen

kingpin separa el parseo de la ejecución: primero declaras la gramática, luego adjuntas callbacks Action que reciben valores completamente validados.

Los enums restringen cadenas a un conjunto fijo; los contadores y las URLs se parsean en tipos nativos sin llamadas manuales a strconv.

La UX avanzada significa fallar rápido con mensajes precisos antes de que se ejecute cualquier E/S de red o archivo.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

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

Cuándo usar esto:

Mantener un binario existente basado en kingpin (herramientas internas heredadas).
Estudiar gramáticas de CLI fluidas con validación de enums y tipos.
Prototipar validación estricta de argumentos antes de comprometerse con cobra.

Prefiere cobra para trabajo nuevo a menos que estés extendiendo código ya construido sobre kingpin.

Ejemplo de Trabajo

package main
 
import (
    "fmt"
    "os"
    "time"
 
    "github.com/alecthomas/kingpin/v2"
)
 
var (
    app     = kingpin.New("ship", "herramienta de envío")
    verbose = app.Flag("verbose", "salida detallada").Short('v').Bool()
    mode    = app.Flag("mode", "modo de ejecución").Enum("dry", "apply")
    timeout = app.Flag("timeout", "tiempo de espera de la operación").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", "ejecutar envío")
 
func run(verbose bool, mode string, timeout time.Duration) {
    fmt.Printf("verbose=%v mode=%s timeout=%s\n", verbose, mode, timeout)
}

Lo que esto demuestra:

Enum rechaza valores fuera de dry y apply en tiempo de parseo.
Los flags Duration parsean la sintaxis de duración de Go sin métodos Set personalizados.
Los subcomandos son nodos app.Command; FullCommand() identifica cuál coincidió.
kingpin.MustParse sale en errores de gramática antes de que run se ejecute.

Inmersión Profunda

Cómo Funciona

kingpin construye un árbol de parseo en la inicialización del paquete (el patrón típico usa variables a nivel de paquete).
Parse consume os.Args[1:], aplica valores predeterminados, realiza la coerción de tipos y devuelve la cadena del comando seleccionado.
Los argumentos requeridos usan .Required(); los opcionales posicionales usan .String() sin Required.
Las plantillas de ayuda y versión son personalizables como otros frameworks.

Características de Validación de un Vistazo

API	Propósito
`.Enum("a", "b")`	Restringir flag o argumento de cadena
`.Required()`	Fallar el parseo si falta
`.Short('v')`	Alias de una sola letra
`.Default("10s")`	Valor predeterminado pre-parseo para flags tipados
`.ExistingFile()`	La ruta debe existir en disco
`.URL()`	Parsear y validar la forma de la URL

Migración a cobra

kingpin	equivalente en cobra
`app.Flag(...).Bool()`	`cmd.Flags().BoolVar`
`app.Arg(...).Required()`	`Args: cobra.ExactArgs(1)` + `RunE`
`.Enum(...)`	validación personalizada en `PreRunE` o `MarkFlagRequired` + verificación de conjunto permitido
`app.Command("run", ...)`	`&cobra.Command{Use: "run"}`

Notas de Go

Las variables de kingpin a nivel de paquete se ejecutan al inicializar; mantén las declaraciones en paquetes cmd, no en bibliotecas.
Después de MustParse, la lógica de negocio debe vivir en funciones simples para que sean testeables.
Si migras, porta un subcomando a la vez detrás de pruebas de integración usando os/exec.

Trampas

Repositorio original archivado - Las correcciones de seguridad pueden retrasarse; planifica la migración para herramientas distribuidas externamente. Solución: rastrea los problemas de paridad con cobra en un ticket y congela nuevos comandos de kingpin.
Acoplamiento por orden de inicialización - Las variables app globales hacen que las pruebas dependan del orden. Solución: envuelve el parseo + acción en funciones que acepten []string.
Enum en flag no establecido - Los enums requeridos deben tener valores predeterminados o ser flags requeridos. Solución: documenta los valores válidos en las cadenas de ayuda.
Mezcla de kingpin y flags de la biblioteca estándar - Dos parseadores luchan por os.Args. Solución: un framework por binario.
Anidamiento excesivo de comandos - Los árboles profundos perjudican la descubribilidad. Solución: aplana los verbos o añade grupos temáticos en la ayuda.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
cobra	Nuevas herramientas, ecosistema k8s	Solo mantienes kingpin heredado
urfave/cli v2	Estructura de app basada en callbacks	Necesitas scaffolds de kubebuilder
kong	Las etiquetas de struct controlan la CLI	El equipo ya conoce kingpin
stdlib flag	Dos flags en total	La validación de enums es manual

Preguntas Frecuentes

¿Es kingpin seguro para nuevos proyectos?

Prefiere cobra o urfave/cli para código nuevo.

kingpin es apropiado cuando extiendes un binario existente ya escrito con él.

¿Cómo difieren los enums de `flag.Value` personalizado?

Los enums de kingpin se declaran en el momento de la construcción de la gramática y se validan antes de que se ejecuten las acciones.

flag.Value valida por flag en la biblioteca estándar con más código repetitivo.

¿Puede kingpin generar completado de shell?

El soporte es limitado en comparación con cobra.

Planifica scripts de completado manuales o migra si el completado con tabulación es crítico.

¿Cómo pruebo los comandos de kingpin?

Llama a app.Parse([]string{"run", "--mode=dry"}) sin tocar os.Args, o prueba la función run después del parseo con valores inyectados.

¿Qué pasa con los flags mutuamente excluyentes requeridos?

Valida en la Action después del parseo o migra a cobra MarkFlagsMutuallyExclusive (características de pflag en Go 1.22+).

Documenta los conflictos claramente en el texto de ayuda.

¿Cómo maneja kingpin la ayuda de subcomandos?

Cada Command obtiene su propia sección de ayuda generada a partir de las definiciones fluidas.

Mantén las cadenas Help orientadas a la acción ("ejecutar envío", no "comando de ejecución").

¿Son los flags cortos portables a Windows?

Sí para CLIs de Go; los usuarios de PowerShell todavía esperan flags largos en los scripts.

Documenta las formas portables en los ejemplos de README.

¿Cómo funcionan los validadores de archivos?

.ExistingFile() y .ExistingDir() hacen stat de las rutas durante el parseo.

Falla rápido antes de subidas lentas cuando las rutas son incorrectas.

¿Deberían las bibliotecas importar kingpin?

No.

Mantén la gramática de la CLI en los paquetes main o cmd para que los consumidores de la biblioteca no se vean obligados a usar un framework de CLI.

¿Qué patrones de UX se transfieren a cobra?

Validar temprano, flags tipados, enums explícitos y argumentos requeridos se mapean directamente a PreRunE de cobra y validadores de flags.

Trata el código de kingpin como una especificación al reescribir comandos.

Relacionado

Árboles de Comandos de cobra & urfave/cli - árbol moderno recomendado
Paquete flag & Flags Estilo POSIX - línea base de la biblioteca estándar
Salida en Color & Errores Amigables para el Usuario - presentación de errores de parseo
Conceptos Básicos de Herramientas CLI - patrones de validación manual
Mejores Prácticas para Herramientas CLI - higiene de pruebas y migración

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC Green Tea, modernizadores de go fix - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación), y golangci-lint (última - verificar conjunto de linters en la compilación).

Influyó en frameworks posteriores y sigue siendo útil para leer herramientas heredadas.

Resumen

kingpin separa el parseo de la ejecución: primero declaras la gramática, luego adjuntas callbacks Action que reciben valores completamente validados.

Los enums restringen cadenas a un conjunto fijo; los contadores y las URLs se parsean en tipos nativos sin llamadas manuales a strconv.

La UX avanzada significa fallar rápido con mensajes precisos antes de que se ejecute cualquier E/S de red o archivo.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

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

Cuándo usar esto:

Mantener un binario existente basado en kingpin (herramientas internas heredadas).
Estudiar gramáticas de CLI fluidas con validación de enums y tipos.
Prototipar validación estricta de argumentos antes de comprometerse con cobra.

Prefiere cobra para trabajo nuevo a menos que estés extendiendo código ya construido sobre kingpin.

Ejemplo de Trabajo

package main
 
import (
    "fmt"
    "os"
    "time"
 
    "github.com/alecthomas/kingpin/v2"
)
 
var (
    app     = kingpin.New("ship", "herramienta de envío")
    verbose = app.Flag("verbose", "salida detallada").Short('v').Bool()
    mode    = app.Flag("mode", "modo de ejecución").Enum("dry", "apply")
    timeout = app.Flag("timeout", "tiempo de espera de la operación").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", "ejecutar envío")
 
func run(verbose bool, mode string, timeout time.Duration) {
    fmt.Printf("verbose=%v mode=%s timeout=%s\n", verbose, mode, timeout)
}

Lo que esto demuestra:

Enum rechaza valores fuera de dry y apply en tiempo de parseo.
Los flags Duration parsean la sintaxis de duración de Go sin métodos Set personalizados.
Los subcomandos son nodos app.Command; FullCommand() identifica cuál coincidió.
kingpin.MustParse sale en errores de gramática antes de que run se ejecute.

Inmersión Profunda

Cómo Funciona

kingpin construye un árbol de parseo en la inicialización del paquete (el patrón típico usa variables a nivel de paquete).
Parse consume os.Args[1:], aplica valores predeterminados, realiza la coerción de tipos y devuelve la cadena del comando seleccionado.
Los argumentos requeridos usan .Required(); los opcionales posicionales usan .String() sin Required.
Las plantillas de ayuda y versión son personalizables como otros frameworks.

Características de Validación de un Vistazo

API	Propósito
`.Enum("a", "b")`	Restringir flag o argumento de cadena
`.Required()`	Fallar el parseo si falta
`.Short('v')`	Alias de una sola letra
`.Default("10s")`	Valor predeterminado pre-parseo para flags tipados
`.ExistingFile()`	La ruta debe existir en disco
`.URL()`	Parsear y validar la forma de la URL

Migración a cobra

kingpin	equivalente en cobra
`app.Flag(...).Bool()`	`cmd.Flags().BoolVar`
`app.Arg(...).Required()`	`Args: cobra.ExactArgs(1)` + `RunE`
`.Enum(...)`	validación personalizada en `PreRunE` o `MarkFlagRequired` + verificación de conjunto permitido
`app.Command("run", ...)`	`&cobra.Command{Use: "run"}`

Notas de Go

Las variables de kingpin a nivel de paquete se ejecutan al inicializar; mantén las declaraciones en paquetes cmd, no en bibliotecas.
Después de MustParse, la lógica de negocio debe vivir en funciones simples para que sean testeables.
Si migras, porta un subcomando a la vez detrás de pruebas de integración usando os/exec.

Trampas

Repositorio original archivado - Las correcciones de seguridad pueden retrasarse; planifica la migración para herramientas distribuidas externamente. Solución: rastrea los problemas de paridad con cobra en un ticket y congela nuevos comandos de kingpin.
Acoplamiento por orden de inicialización - Las variables app globales hacen que las pruebas dependan del orden. Solución: envuelve el parseo + acción en funciones que acepten []string.
Enum en flag no establecido - Los enums requeridos deben tener valores predeterminados o ser flags requeridos. Solución: documenta los valores válidos en las cadenas de ayuda.
Mezcla de kingpin y flags de la biblioteca estándar - Dos parseadores luchan por os.Args. Solución: un framework por binario.
Anidamiento excesivo de comandos - Los árboles profundos perjudican la descubribilidad. Solución: aplana los verbos o añade grupos temáticos en la ayuda.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
cobra	Nuevas herramientas, ecosistema k8s	Solo mantienes kingpin heredado
urfave/cli v2	Estructura de app basada en callbacks	Necesitas scaffolds de kubebuilder
kong	Las etiquetas de struct controlan la CLI	El equipo ya conoce kingpin
stdlib flag	Dos flags en total	La validación de enums es manual

Preguntas Frecuentes

¿Es kingpin seguro para nuevos proyectos?

Prefiere cobra o urfave/cli para código nuevo.

kingpin es apropiado cuando extiendes un binario existente ya escrito con él.

¿Cómo difieren los enums de `flag.Value` personalizado?

Los enums de kingpin se declaran en el momento de la construcción de la gramática y se validan antes de que se ejecuten las acciones.

flag.Value valida por flag en la biblioteca estándar con más código repetitivo.

¿Puede kingpin generar completado de shell?

El soporte es limitado en comparación con cobra.

Planifica scripts de completado manuales o migra si el completado con tabulación es crítico.

¿Cómo pruebo los comandos de kingpin?

Llama a app.Parse([]string{"run", "--mode=dry"}) sin tocar os.Args, o prueba la función run después del parseo con valores inyectados.

¿Qué pasa con los flags mutuamente excluyentes requeridos?

Valida en la Action después del parseo o migra a cobra MarkFlagsMutuallyExclusive (características de pflag en Go 1.22+).

Documenta los conflictos claramente en el texto de ayuda.

¿Cómo maneja kingpin la ayuda de subcomandos?

Cada Command obtiene su propia sección de ayuda generada a partir de las definiciones fluidas.

Mantén las cadenas Help orientadas a la acción ("ejecutar envío", no "comando de ejecución").

¿Son los flags cortos portables a Windows?

Sí para CLIs de Go; los usuarios de PowerShell todavía esperan flags largos en los scripts.

Documenta las formas portables en los ejemplos de README.

¿Cómo funcionan los validadores de archivos?

.ExistingFile() y .ExistingDir() hacen stat de las rutas durante el parseo.

Falla rápido antes de subidas lentas cuando las rutas son incorrectas.

¿Deberían las bibliotecas importar kingpin?

No.

Mantén la gramática de la CLI en los paquetes main o cmd para que los consumidores de la biblioteca no se vean obligados a usar un framework de CLI.

¿Qué patrones de UX se transfieren a cobra?

Validar temprano, flags tipados, enums explícitos y argumentos requeridos se mapean directamente a PreRunE de cobra y validadores de flags.

Trata el código de kingpin como una especificación al reescribir comandos.

Relacionado

Árboles de Comandos de cobra & urfave/cli - árbol moderno recomendado
Paquete flag & Flags Estilo POSIX - línea base de la biblioteca estándar
Salida en Color & Errores Amigables para el Usuario - presentación de errores de parseo
Conceptos Básicos de Herramientas CLI - patrones de validación manual
Mejores Prácticas para Herramientas CLI - higiene de pruebas y migración

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado GC Green Tea, modernizadores de go fix - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación), y golangci-lint (última - verificar conjunto de linters en la compilación).

kingpin & UX avanzada de CLI

Buscar en la documentación

kingpin & UX avanzada de CLI