Noções Básicas de Ferramentas CLI

10 exemplos para você começar com ferramentas de linha de comando Go - 7 básicos e 3 intermediários.

Pré-requisitos

• Instale o Go 1.26.x ou posterior em go.dev/dl.
• Crie um módulo: mkdir clilab && cd clilab && go mod init example.com/clilab.
• Salve cada trecho como main.go (ou arquivos separados em um pacote) e execute com go run ..
• Passe flags após -- ao usar go run: go run . -- -name=Ada.

Exemplos Básicos

1. Hello World com flag

O pacote flag da biblioteca padrão analisa -name antes que a lógica main seja executada.

package main
 
import (
    "flag"
    "fmt"
)
 
func main() {
    name := flag.String("name", "world", "alvo da saudação")
    flag.Parse()
    fmt.Printf("hello, %s\n", *name)
}

• flag.String registra um ponteiro atualizado durante flag.Parse().
• Padrões são aplicados quando a flag é omitida.
• Flags desconhecidas imprimem o uso e saem com código não-zero, a menos que você personalize o comportamento.

Relacionado: Pacote flag e Flags Estilo POSIX - FlagSet e texto de uso

2. Flags Booleanas e Numéricas

Misture flags Bool, Int e Duration em um único comando.

package main
 
import (
    "flag"
    "fmt"
    "time"
)
 
func main() {
    verbose := flag.Bool("v", false, "saída verbosa")
    count := flag.Int("n", 1, "contagem de repetição")
    delay := flag.Duration("delay", 0, "pausa entre linhas")
    flag.Parse()
    for i := 0; i < *count; i++ {
        if *verbose {
            fmt.Println("tick", i)
        }
        time.Sleep(*delay)
    }
}

• -v e -v=true ambos definem uma flag booleana.
• flag.Duration aceita 300ms, 2s, 1m.
• Analise todas as flags antes de ler flag.Args() para argumentos posicionais.

Relacionado: Design de CLI em Go: Binário Único, Inicialização Rápida - por que Go se encaixa em CLIs

3. Argumentos Posicionais Após Flags

flag.Args() retorna tokens que não foram consumidos como flags.

package main
 
import (
    "flag"
    "fmt"
)
 
func main() {
    flag.Parse()
    args := flag.Args()
    if len(args) == 0 {
        fmt.Println("uso: tool <file>...")
        return
    }
    for _, path := range args {
        fmt.Println("processar", path)
    }
}

• Flags podem aparecer antes ou depois de posicionais ao usar o conjunto padrão (estilo POSIX).
• Valide a aridade explicitamente; não assuma que os usuários passam a contagem correta.
• Imprima uma linha de uso curta quando os argumentos necessários estiverem faltando.

Relacionado: Saída Colorida e Erros Amigáveis ao Usuário - mensagens stderr

4. Função de Uso Personalizada

Substitua o texto de uso padrão por ajuda amigável ao operador.

package main
 
import (
    "flag"
    "fmt"
    "os"
)
 
func main() {
    flag.Usage = func() {
        fmt.Fprintf(os.Stderr, "uso: %s [flags] <target>\n", os.Args[0])
        flag.PrintDefaults()
    }
    flag.Parse()
}

• flag.Usage é executado em erros de análise e quando você o chama manualmente.
• Escreva a ajuda no stderr para que o stdout permaneça canalizável.
• PrintDefaults lista as flags registradas com seus padrões.

Relacionado: Pacote flag e Flags Estilo POSIX - convenções de uso

5. FlagSet Dedicado por Subcomando

Isole flags ao despachar em os.Args[1].

package main
 
import (
    "flag"
    "fmt"
    "os"
)
 
func main() {
    if len(os.Args) < 2 {
        fmt.Println("uso: tool <init|run>")
        os.Exit(1)
    }
    switch os.Args[1] {
    case "init":
        fs := flag.NewFlagSet("init", flag.ExitOnError)
        dir := fs.String("dir", ".", "diretório do projeto")
        _ = fs.Parse(os.Args[2:])
        fmt.Println("init em", *dir)
    case "run":
        fmt.Println("run")
    default:
        fmt.Println("subcomando desconhecido")
        os.Exit(1)
    }
}

• flag.NewFlagSet evita colisões entre flags de subcomandos.
• Passe os.Args[2:] para que o nome do subcomando não seja reanalisado.
• flag.ExitOnError sai em flags desconhecidas apenas para aquele subcomando.

Relacionado: Árvores de Comando cobra & urfave/cli - árvores de comando estruturadas

6. Códigos de Saída para Scripts

Saídas não-zero sinalizam falha para scripts de shell e CI.

package main
 
import (
    "errors"
    "fmt"
    "os"
)
 
func run() error {
    return errors.New("configuração ausente")
}
 
func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, "erro:", err)
        os.Exit(1)
    }
}

• Reserve os.Exit para main; funções deferidas não são executadas após os.Exit.
• Documente códigos de saída estáveis quando os operadores automatizarem a remediação.
• Imprima erros no stderr, não no stdout.

Relacionado: Saída Colorida e Erros Amigáveis ao Usuário - convenções de código de saída

7. Flag de Versão via ldflags

Injete metadados de build no tempo de compilação.

package main
 
import (
    "flag"
    "fmt"
)
 
var version = "dev"
 
func main() {
    showVersion := flag.Bool("version", false, "imprimir versão e sair")
    flag.Parse()
    if *showVersion {
        fmt.Println(version)
        return
    }
}

• Compile com: go build -ldflags "-X main.version=1.0.0".
• A variável version deve ser uma string em nível de pacote.
• Emparelhe --version com carimbos de CI de tags git.

Relacionado: Melhores Práticas para Ferramentas CLI - versionamento e distribuição

Exemplos Intermediários

8. Padrões de Variáveis de Ambiente

Leia o env antes dos padrões de flag para configuração estilo doze fatores.

package main
 
import (
    "flag"
    "fmt"
    "os"
)
 
func envOr(key, fallback string) string {
    if v := os.Getenv(key); v != "" {
        return v
    }
    return fallback
}
 
func main() {
    def := envOr("API_URL", "http://localhost:8080")
    api := flag.String("api", def, "URL base da API")
    flag.Parse()
    fmt.Println(*api)
}

• Flags devem substituir o env quando ambos estiverem definidos (verifique após Parse).
• Documente a precedência no README e em --help.
• Viper automatiza a mesclagem; isso mostra o padrão manual.

Relacionado: Configuração: Viper, Env e Arquivos de Configuração - configuração em camadas

9. Testando Flags com FlagSet Isolado

Troque o conjunto global de flags em testes para evitar poluição.

package main
 
import (
    "flag"
    "testing"
)
 
func TestGreetFlag(t *testing.T) {
    fs := flag.NewFlagSet("test", flag.ContinueOnError)
    name := fs.String("name", "world", "")
    err := fs.Parse([]string{"-name", "Ada"})
    if err != nil || *name != "Ada" {
        t.Fatalf("erro de parse=%v nome=%q", err, *name)
    }
}

• flag.ContinueOnError permite que os testes afirmem falhas de análise.
• Prefira funções Run do pacote testing que aceitam []string em vez de globais.
• Cobra expõe SetArgs para o mesmo padrão de isolamento.

Relacionado: Melhores Práticas para Ferramentas CLI - testando CLIs

10. Comando Raiz cobra Mínimo

cobra adiciona geração de ajuda e roteamento de subcomandos.

package main
 
import (
    "fmt"
    "github.com/spf13/cobra"
)
 
func main() {
    root := &cobra.Command{
        Use:   "demo",
        Short: "CLI de demonstração",
        RunE: func(cmd *cobra.Command, args []string) error {
            fmt.Println("demo ok")
            return nil
        },
    }
    if err := root.Execute(); err != nil {
        panic(err)
    }
}

• Execute go get github.com/spf13/cobra@latest antes de compilar.
• RunE retorna erros; Execute os imprime e define o código de saída 1.
• Adicione comandos filhos com root.AddCommand para ferramentas reais.

Relacionado: Árvores de Comando cobra & urfave/cli - flags persistentes e conclusão

Versões da Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, 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).