Build de Referência: CLI de Produção com cobra

Este build de referência é myctl, uma ferramenta de operador multi-comando: migrações de banco de dados, status de cluster, alvos controlados por configuração, uma UI de progresso Bubble Tea e um pipeline goreleaser que envia arquivos compactados assinados para Linux, macOS e Windows.

Use-o quando sua equipe precisar de mais do que um único main com flags, mas menos do que um produto de plataforma completo.

Resumo

CLIs de produção em Go compilam para um único binário, iniciam rapidamente e se comportam de forma previsível em scripts.

Este build usa cobra para árvores de comandos, viper para configuração em camadas, slog para logs legíveis por máquina quando --json é definido, e Bubble Tea para fluxos interativos que ainda respeitam o cancelamento Ctrl+C.

Comandos separam operações de leitura (seguras para CI) de operações de escrita (prompts de confirmação, a menos que --yes).

A automação de release embuti a versão, commit e data de build via -ldflags para suporte.

Receita

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

Quando usar este layout:

• Operadores executam a ferramenta em CI, sessões SSH e laptops usando os mesmos comandos.
• Subcomandos mapeiam para fluxos de trabalho de domínio (migrate, deploy, diagnose), não pacotes Go.
• Você precisa de precedência de arquivo de configuração + env + flag sem código de parsing customizado.
• Tarefas longas se beneficiam de uma TUI, enquanto tarefas curtas permanecem em stdout simples.

Exemplo de Trabalho

// 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)
    }
}

O que isso demonstra:

• PersistentPreRunE carrega a configuração antes que cada subcomando seja executado.
• Variáveis de ambiente como MYCTL_CONTEXT são mapeadas via viper.AutomaticEnv().
• main permanece como um caminho de execução de linha única para facilitar a compilação cruzada.

Análise Profunda

Como Funciona

• Invocação: shell chama subcomando → cobra parseia flags → viper mescla arquivo/env → comando RunE executa com context.Context quando IO é de longa duração.
• Saída: tabelas humanas para stdout; diagnósticos para stderr; --json alterna o manipulador slog no stderr para agentes.
• Erros: retorna error de RunE; mapeia falhas conhecidas para códigos de saída 2 (uso) e 3 (sucesso parcial) em main, se necessário.
• Release: GoReleaser constrói arquivos compactados de matriz, checksums e assinaturas cosign opcionais.

Taxonomia de Comandos

Integração com 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
        },
    }
}

• Passa o contexto do comando cobra para o Tea para que SIGINT cancele os loops de polling.
• Retorna para a saída time.Ticker simples quando isatty é falso.

Notas de Go

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

• Embuti assets //go:embed apenas quando a CLI envia templates; mantém o tamanho do binário previsível.
• Use cobra.Command.SilenceUsage em erros de tempo de execução para que os usuários não vejam spam de uso após um migrate falho.

Armadilhas

• Estado global do Viper em testes - testes paralelos competem pela configuração. Correção: resete o viper em t.Cleanup ou injete a struct de configuração em vez de globais em novos comandos.
• Sem contexto em chamadas de rede - Ctrl+C não para clientes de API pendentes. Correção: use cmd.Context() em cada RunE.
• Comandos de escrita sem salvaguardas - CI destrói a produção. Correção: exija --yes ou confirmação interativa quando stdin não for um TTY.
• Formatos de saída inconsistentes - scripts quebram com desvio de colunas. Correção: --output json estável em comandos de leitura; use semver no esquema.
• goreleaser sem testes de fumaça compilados cruzados - builds arm64 quebrados são enviados silenciosamente. Correção: go test mais myctl version em cada arquivo compactado construído em CI.
• Logging para stdout - polui fluxos de trabalho canalizados. Correção: logs para stderr; dados para stdout.

Alternativas

FAQs

Relacionado

• cobra & urfave/cli Command Trees - Padrões de árvore de comandos
• Configuration: viper, Env & Config Files - Camadas de configuração
• Bubble Tea Terminal UI & Progress Bars - Detalhes da TUI
• CLI Design in Go: Single Binary, Fast Startup - Princípios de UX
• Case Studies Basics - Lendo builds de referência
• Reference Build: Cloud-Native REST Microservice - Serviço que o CLI opera

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizers - verifique o patch na build), chi (última - verifique na build), gin (última - verifique na build), echo (última - verifique na build), google.golang.org/grpc (última - verifique na build), sigs.k8s.io/controller-runtime (última - verifique na build), kubebuilder (última - verifique na build), tinygo (última - verifique os alvos de placa na build), wazero (última - verifique na build) e golangci-lint (última - verifique o conjunto de linters na build).