Build de Referencia: CLI de Producción con cobra

Este build de referencia es myctl, una herramienta de operador multi-comando: migraciones de base de datos, estado del clúster, objetivos controlados por configuración, una UI de progreso con Bubble Tea y un pipeline de goreleaser que distribuye archivos firmados para Linux, macOS y Windows.

Úsalo cuando tu equipo necesite más que un único main con flags, pero menos que un producto de plataforma completo.

Resumen

Las CLIs de producción en Go compilan en un solo binario, inician rápido y se comportan predeciblemente en scripts.

Este build usa cobra para árboles de comandos, viper para configuración en capas, slog para logs legibles por máquina cuando se establece --json, y Bubble Tea para flujos interactivos que aún respetan la cancelación con Ctrl+C.

Los comandos separan las operaciones de lectura (seguras para CI) de las operaciones de escritura (prompts de confirmación a menos que se use --yes).

La automatización de lanzamientos incrusta la versión, el commit y la fecha de build a través de -ldflags para la capacidad de soporte.

Receta

myctl --config ~/.config/myctl/config.yaml cluster status --context prod
myctl migrate up --dsn "$DATABASE_URL" --yes
myctl watch jobs --interval 2s
myctl version --output json

Cuándo usar este diseño:

• Los operadores ejecutan la herramienta en CI, sesiones SSH y laptops contra los mismos comandos.
• Los subcomandos se mapean a flujos de trabajo de dominio (migrate, deploy, diagnose), no a paquetes de Go.
• Necesitas precedencia de archivo de configuración + env + flag sin código de análisis personalizado.
• Las tareas largas se benefician de una TUI mientras que las tareas cortas permanecen en stdout plano.

Ejemplo de Trabajo

// internal/cli/root.go
package cli
 
import (
    "github.com/spf13/cobra"
    "github.com/spf13/viper"
)
 
func NewRoot() *cobra.Command {
    root := &cobra.Command{
        Use:   "myctl",
        Short: "Operate shop-api infrastructure",
        PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
            return initConfig(cmd)
        },
    }
    root.PersistentFlags().String("config", "", "config file")
    root.PersistentFlags().Bool("json", false, "JSON logs to stderr")
    _ = viper.BindPFlag("config", root.PersistentFlags().Lookup("config"))
    root.AddCommand(newMigrateCmd(), newStatusCmd(), newWatchCmd(), newVersionCmd())
    return root
}
 
func initConfig(cmd *cobra.Command) error {
    viper.SetEnvPrefix("MYCTL")
    viper.AutomaticEnv()
    if path, _ := cmd.Flags().GetString("config"); path != "" {
        viper.SetConfigFile(path)
        return viper.ReadInConfig()
    }
    viper.SetConfigName("config")
    viper.AddConfigPath("$HOME/.config/myctl")
    _ = viper.ReadInConfig() // optional file
    return nil
}

// cmd/myctl/main.go
package main
 
import (
    "os"
 
    "example.com/myctl/internal/cli"
)
 
var version = "dev"
 
func main() {
    root := cli.NewRoot()
    root.Version = version
    if err := root.Execute(); err != nil {
        os.Exit(1)
    }
}

Lo que esto demuestra:

• PersistentPreRunE carga la configuración antes de que se ejecute cada subcomando.
• Las variables de entorno como MYCTL_CONTEXT se mapean a través de viper.AutomaticEnv().
• main sigue siendo una ruta de ejecución de una sola línea para facilitar la compilación cruzada.

Análisis Profundo

Cómo Funciona

• Invocación: el shell llama al subcomando → cobra analiza los flags → viper fusiona archivo/entorno → la RunE del comando se ejecuta con context.Context cuando la E/S es de larga duración.
• Salida: tablas humanas a stdout; diagnósticos a stderr; --json cambia el manejador de slog en stderr para agentes.
• Errores: devuelve error desde RunE; mapea fallos conocidos a códigos de salida 2 (uso) y 3 (éxito parcial) en main si es necesario.
• Lanzamiento: GoReleaser construye archivos de matriz, checksums y firmas cosign opcionales.

Taxonomía de Comandos

Integración con Bubble Tea

// internal/cli/watch.go - simplificado
func newWatchCmd() *cobra.Command {
    return &cobra.Command{
        Use:   "watch",
        RunE: func(cmd *cobra.Command, args []string) error {
            p := tea.NewProgram(newJobsModel(fetchJobs), tea.WithContext(cmd.Context()))
            _, err := p.Run()
            return err
        },
    }
}

• Pasa el contexto del comando cobra a Tea para que SIGINT cancele los bucles de sondeo.
• Vuelve a la Ticker de time plano cuando isatty es falso.

Notas de Go

go build -ldflags="-X main.version=$(git describe --tags --always)" -o myctl ./cmd/myctl

• Incrusta activos //go:embed solo cuando la CLI envía plantillas; mantén el tamaño del binario predecible.
• Usa cobra.Command.SilenceUsage en errores de tiempo de ejecución para que los usuarios no vean spam de uso después de una migración fallida.

Trampas Comunes

• Estado global de Viper en pruebas - las pruebas paralelas compiten por la configuración. Solución: reinicia viper en t.Cleanup o inyecta la estructura de configuración en lugar de globales en nuevos comandos.
• Sin contexto en llamadas de red - Ctrl+C no detiene clientes de API colgados. Solución: usa cmd.Context() en cada RunE.
• Comandos de escritura sin salvaguardas - la CI destruye la producción. Solución: requiere --yes o confirmación interactiva cuando stdin no es un TTY.
• Formatos de salida inconsistentes - los scripts se rompen por cambios de columna. Solución: --output json estable en comandos de lectura; versiona el esquema semánticamente.
• goreleaser sin pruebas de humo compiladas cruzadamente - se envían compilaciones de arm64 rotas silenciosamente. Solución: go test más myctl version en cada archivo compilado en CI.
• Registrar en stdout - contamina los flujos de trabajo canalizados. Solución: logs a stderr; datos a stdout.

Alternativas

Preguntas Frecuentes

Relacionado

• cobra & urfave/cli Command Trees - Patrones de árboles de comandos
• Configuration: viper, Env & Config Files - Capas de configuración
• Bubble Tea Terminal UI & Progress Bars - Detalle de TUI
• CLI Design in Go: Single Binary, Fast Startup - Principios de UX
• Case Studies Basics - Lectura de builds de referencia
• Reference Build: Cloud-Native REST Microservice - Servicio que opera la CLI

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