Fundamentos de Herramientas CLI

10 ejemplos para empezar con herramientas de línea de comandos en Go: 7 básicos y 3 intermedios.

Prerrequisitos

• Instala Go 1.26.x o posterior desde go.dev/dl.
• Crea un módulo: mkdir clilab && cd clilab && go mod init example.com/clilab.
• Guarda cada fragmento como main.go (o archivos separados en un mismo paquete) y ejecútalo con go run ..
• Pasa las flags después de -- cuando uses go run: go run . -- -name=Ada.

Ejemplos Básicos

1. Hola Mundo con flag

El paquete flag de la librería estándar analiza -name antes de que se ejecute la lógica de main.

package main
 
import (
    "flag"
    "fmt"
)
 
func main() {
    name := flag.String("name", "world", "objetivo del saludo")
    flag.Parse()
    fmt.Printf("hola, %s\n", *name)
}

• flag.String registra un puntero que se actualiza durante flag.Parse().
• Los valores predeterminados se aplican cuando se omite la flag.
• Las flags desconocidas imprimen la ayuda y salen con código distinto de cero a menos que personalices el comportamiento.

Relacionado: Paquete flag y Flags Estilo POSIX - FlagSet y texto de uso

2. Flags Booleanas y Numéricas

Mezcla flags Bool, Int y Duration en un mismo comando.

package main
 
import (
    "flag"
    "fmt"
    "time"
)
 
func main() {
    verbose := flag.Bool("v", false, "salida detallada")
    count := flag.Int("n", 1, "número de repeticiones")
    delay := flag.Duration("delay", 0, "pausa entre líneas")
    flag.Parse()
    for i := 0; i < *count; i++ {
        if *verbose {
            fmt.Println("tick", i)
        }
        time.Sleep(*delay)
    }
}

• -v y -v=true ambos establecen una flag booleana.
• flag.Duration acepta 300ms, 2s, 1m.
• Analiza todas las flags antes de leer flag.Args() para argumentos posicionales.

Relacionado: Diseño CLI en Go: Binario Único, Arranque Rápido - por qué Go es adecuado para CLIs

3. Argumentos Posicionales Después de Flags

flag.Args() devuelve los tokens que no fueron consumidos como flags.

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

• Las flags pueden aparecer antes o después de las posicionales cuando se usa el conjunto predeterminado (estilo POSIX).
• Valida la aridad explícitamente; no asumas que los usuarios pasan la cantidad correcta.
• Imprime una línea de uso corta cuando faltan argumentos requeridos.

Relacionado: Salida en Color y Errores Amigables para el Usuario - mensajes en stderr

4. Función de Uso Personalizada

Reemplaza el texto de uso predeterminado con ayuda amigable para el operador.

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

• flag.Usage se ejecuta en errores de análisis y cuando lo llamas manualmente.
• Escribe la ayuda en stderr para que stdout siga siendo canalizable.
• PrintDefaults lista las flags registradas con sus valores predeterminados.

Relacionado: Paquete flag y Flags Estilo POSIX - convenciones de uso

5. FlagSet Dedicado por Subcomando

Aísla las flags al despachar en 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", ".", "directorio del proyecto")
        _ = fs.Parse(os.Args[2:])
        fmt.Println("inicializando en", *dir)
    case "run":
        fmt.Println("ejecutando")
    default:
        fmt.Println("subcomando desconocido")
        os.Exit(1)
    }
}

• flag.NewFlagSet evita colisiones entre flags de subcomandos.
• Pasa os.Args[2:] para que el nombre del subcomando no se vuelva a analizar.
• flag.ExitOnError sale en caso de flags desconocidas solo para ese subcomando.

Relacionado: Árboles de Comandos de cobra y urfave/cli - árboles de comandos estructurados

6. Códigos de Salida para Scripts

Las salidas distintas de cero señalan fallos a scripts de shell y CI.

package main
 
import (
    "errors"
    "fmt"
    "os"
)
 
func run() error {
    return errors.New("configuración faltante")
}
 
func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, "error:", err)
        os.Exit(1)
    }
}

• Reserva os.Exit para main; las funciones diferidas no se ejecutan después de os.Exit.
• Documenta códigos de salida estables cuando los operadores automatizan la remediación.
• Imprime errores en stderr, no en stdout.

Relacionado: Salida en Color y Errores Amigables para el Usuario - convenciones de códigos de salida

7. Flag de Versión con ldflags

Inyecta metadatos de compilación en tiempo de compilación.

package main
 
import (
    "flag"
    "fmt"
)
 
var version = "dev"
 
func main() {
    showVersion := flag.Bool("version", false, "imprime la versión y sale")
    flag.Parse()
    if *showVersion {
        fmt.Println(version)
        return
    }
}

• Compila con: go build -ldflags "-X main.version=1.0.0".
• La variable version debe ser un string a nivel de paquete.
• Empareja --version con sellos de CI de etiquetas git.

Relacionado: Mejores Prácticas para Herramientas CLI - versionado y distribución

Ejemplos Intermedios

8. Valores Predeterminados de Variables de Entorno

Lee la variable de entorno antes que los valores predeterminados de las flags para la configuración estilo doce factores.

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 de la API")
    flag.Parse()
    fmt.Println(*api)
}

• Las flags deben anular las variables de entorno cuando ambas están establecidas (verifica después de Parse).
• Documenta la precedencia en README y --help.
• Viper automatiza la fusión; esto muestra el patrón manual.

Relacionado: Configuración: Viper, Env y Archivos de Configuración - configuración en capas

9. Pruebas de Flags con FlagSet Aislado

Intercambia el conjunto de flags global en las pruebas para evitar contaminación.

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("error de análisis err=%v name=%q", err, *name)
    }
}

• flag.ContinueOnError permite a las pruebas afirmar fallos de análisis.
• Prefiere las funciones Run del paquete testing que aceptan []string en lugar de globales.
• Cobra expone SetArgs para el mismo patrón de aislamiento.

Relacionado: Mejores Prácticas para Herramientas CLI - pruebas de CLIs

10. Comando Raíz Mínimo de cobra

cobra añade generación de ayuda y enrutamiento de subcomandos.

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

• Ejecuta go get github.com/spf13/cobra@latest antes de compilar.
• RunE devuelve errores; Execute los imprime y establece el código de salida 1.
• Añade comandos hijos con root.AddCommand para herramientas reales.

Relacionado: Árboles de Comandos de cobra y urfave/cli - flags persistentes y completado

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