go-spf13-cobra
Advanced CLI development with spf13/cobra. Covers command trees, argument validation, hooks, and shell completion.
SKILL.mdskills/go/go-spf13-cobra/SKILL.md
GitHubCore Concepts
Cobra is built on a structure of Commands, Args, and Flags.
- Commands: The actions (e.g.,
git clone,docker run). - Args: Positional arguments passed to the command.
- Flags: Modifiers for the command (e.g.,
--verbose,-p 8080).
Best Practices
- Use
RunEoverRun—RunEallows returning an error, which Cobra can then format and display. - Standardize Error Handling — Set
SilenceUsage: truein your root command to avoid printing the help block on every logic error. - Use Built-in Arg Validators — Instead of manual length checks, use
cobra.ExactArgs(1),cobra.MinimumNArgs(1), etc. - Persistent Flags — Use
PersistentFlags()for flags that should apply to a command and all its subcommands (e.g.,--configor--verbose). - Output via
OutOrStdout()— Never useos.Stdoutdirectly. Usingcmd.OutOrStdout()makes your CLI testable by allowing you to redirect output.
Command Hooks Lifecycle
Cobra commands follow this execution order:
PersistentPreRunE(Inherited from parents)PreRunERunEPostRunEPersistentPostRunE(Inherited from parents)
Note: A child's PersistentPreRunE overwrites the parent's. If you need both, the child must explicitly call the parent's hook.
Code Example: Root Command
var rootCmd = &cobra.Command{
Use: "myapp",
Short: "My awesome CLI application",
PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
// Initialize config or auth here
return nil
},
RunE: func(cmd *cobra.Command, args []string) error {
return cmd.Help()
},
SilenceUsage: true,
}
Argument Validation
var subCmd = &cobra.Command{
Use: "greet [name]",
Short: "Greets a person",
Args: cobra.ExactArgs(1), // Built-in validator
RunE: func(cmd *cobra.Command, args []string) error {
fmt.Fprintf(cmd.OutOrStdout(), "Hello, %s!\n", args[0])
return nil
},
}
Testing Cobra Commands
func TestCommand(t *testing.T) {
buf := new(bytes.Buffer)
cmd := NewRootCommand()
cmd.SetOut(buf)
cmd.SetArgs([]string{"greet", "World"})
err := cmd.Execute()
assert.NoError(t, err)
assert.Contains(t, buf.String(), "Hello, World!")
}
Anti-patterns
- ❌
os.Exit()inside commands — Prevents cleanup and tests. Return an error fromRunEinstead. - ❌ Global state in commands — Makes concurrent tests impossible. Initialize the command tree per test.
- ❌ Hardcoded
os.Stdout— Breaks testability. Usecmd.OutOrStdout(). - ❌ Ignoring
PersistentPreRunEinheritance — Child commands accidentally skipping parent initialization logic. - ❌ No argument validation — Letting the app panic or fail with "index out of range" instead of a clear usage error.