cobra & urfave/cli Command Trees

kubectl-style tools need nested subcommands, shared global flags, and consistent help text.

cobra (github.com/spf13/cobra) is the most common choice in the Go ecosystem.

urfave/cli v2 (github.com/urfave/cli/v2) offers a struct-driven alternative with hooks and bash completion.

Both compile into the same single binary model; pick based on API taste and ecosystem integration (cobra pairs naturally with viper and controller-runtime scaffolds).

Summary

Command trees map argv to a selected Run or RunE function.

Parent commands hold persistent flags (config path, verbosity) while leaf commands declare action-specific flags.

Execute walks the tree, prints help on errors, and sets exit codes for shell scripts.

Shell completion generators reduce typos for long command paths like mytool db migrate up.

Recipe

Quick-reference recipe card - copy-paste ready.

root := &cobra.Command{Use: "mytool"}
root.PersistentFlags().StringVar(&cfgFile, "config", "", "config file")
root.AddCommand(&cobra.Command{
    Use:   "run",
    Short: "start worker",
    RunE: func(cmd *cobra.Command, args []string) error { return runWorker(cfgFile) },
})
return root.Execute()

When to reach for this:

• More than two subcommands or nested resource verbs (get, describe, delete).
• Shared flags across many commands (--kubeconfig, --namespace).
• You want auto-generated help and shell completion.
• Kubernetes operators generated by kubebuilder (cobra by default).

Working Example

package main
 
import (
    "fmt"
    "os"
 
    "github.com/spf13/cobra"
)
 
var verbose bool
 
func main() {
    root := &cobra.Command{
        Use:   "ship",
        Short: "shipping utilities",
    }
    root.PersistentFlags().BoolVar(&verbose, "verbose", false, "verbose logs")
 
    initCmd := &cobra.Command{
        Use:   "init",
        Short: "initialize workspace",
        RunE: func(cmd *cobra.Command, args []string) error {
            dir, _ := cmd.Flags().GetString("dir")
            if verbose {
                fmt.Println("init", dir)
            }
            return nil
        },
    }
    initCmd.Flags().String("dir", ".", "target directory")
 
    root.AddCommand(initCmd)
    if err := root.Execute(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

What this demonstrates:

• PersistentFlags on root apply to init and future siblings.
• Local flags attach only to initCmd.
• RunE returns errors; Execute handles printing and exit status.
• cmd.Flags().GetString reads parsed values inside the handler.

Deep Dive

How It Works

• cobra builds a tree of *cobra.Command nodes at init time.
• Execute parses global flags, finds the deepest matching command, parses local flags, validates Args, then calls RunE.
• Help merges parent and child documentation; cmd.Help() is callable from code.
• urfave/cli uses cli.App with []*cli.Command and Before/After hooks instead of persistent flags on a struct.

cobra vs urfave/cli

Shell Completion

# bash example after generating completion script
mytool completion bash > /etc/bash_completion.d/mytool

• Register valid flag values with RegisterFlagCompletionFunc.
• Document installation in README for operators using zsh or fish.
• Keep completion fast; avoid network calls during tab press.

Go Notes

• Keep command wiring in cmd/ package; put business logic in internal/.
• Prefer RunE over Run so errors propagate to Execute.
• Use SilenceUsage: true on commands when parse errors should not dump full help.

Gotchas

• Duplicate flag names on parent and child - cobra panics or errors at init. Fix: rename or use persistent only on root.
• Calling Execute from multiple tests without reset - Global state in pflags. Fix: root.SetArgs([]string{"init", "--dir", "/tmp"}) per test.
• Heavy init in every command package - Slow startup for unused subcommands. Fix: lazy imports or split binaries for CI-hot tools.
• urfave/cli v1 API - Old tutorials reference v1; module path changed to /v2. Fix: pin github.com/urfave/cli/v2.
• Missing Args validators - Operators pass wrong arity and get confusing errors. Fix: cobra.MinimumNArgs, custom ValidArgsFunction.

Alternatives

FAQs

Related

• CLI Tools Basics - manual subcommand dispatch
• flag Package & POSIX-Style Flags - stdlib parsing baseline
• Configuration: Viper, Env & Config Files - BindPFlags integration
• kingpin & Advanced CLI UX - typed flag alternative
• CLI Tools Best Practices - distribution and testing

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).