Golang CLI command tree library using spf13/cobra — cobra.Command, RunE vs Run, PersistentPreRunE hook chain, Args validators (NoArgs, ExactArgs, MatchAll, custom), persistent vs local flags, command groups, ValidArgsFunction, RegisterFlagCompletionFunc, ShellCompDirective, usage/help template customization, man-page and markdown doc generation, and testing with SetArgs/SetOut/SetErr. Apply when using or adopting spf13/cobra, or when the codebase imports `github.com/spf13/cobra`. For configuration layering alongside cobra, see the `samber/cc-skills-golang@golang-spf13-viper` skill. For general CLI architecture (project layout, exit codes, signal handling, I/O patterns), see `samber/cc-skills-golang@golang-cli`.
name: golang-spf13-cobra
description: "Golang CLI command tree library using spf13/cobra — cobra.Command, RunE vs Run, PersistentPreRunE hook chain, Args validators (NoArgs, ExactArgs, MatchAll, custom), persistent vs local flags, command groups, ValidArgsFunction, RegisterFlagCompletionFunc, ShellCompDirective, usage/help template customization, man-page and markdown doc generation, and testing with SetArgs/SetOut/SetErr. Apply when using or adopting spf13/cobra, or when the codebase imports github.com/spf13/cobra. For configuration layering alongside cobra, see the samber/cc-skills-golang@golang-spf13-viper skill. For general CLI architecture (project layout, exit codes, signal handling, I/O patterns), see samber/cc-skills-golang@golang-cli."
user-invocable: true
license: MIT
compatibility: Designed for Claude Code, Codex or similar harness, and for projects using Golang.
metadata:
author: samber
version: "1.1.2"
openclaw:
emoji: "🐍"
homepage: https://github.com/samber/cc-skills-golang
requires:
bins:
- go
install: []
skill-library-version: "1.10.2"
allowed-tools: Read Edit Write Glob Grep Bash(go:) Bash(golangci-lint:) Bash(git:) Agent WebFetch mcp__context7__resolve-library-id mcp__context7__query-docs Bash(godig:) Bash(gopls:
paths:
) LSP mcp__gopls__
"**/*.go"
Persona: You are a Go CLI engineer building command trees that feel native to the Unix shell. You design the user-facing surface first, then wire behavior into the right hook.
Modes:
Build — creating a new CLI from scratch: follow command tree setup, hook wiring, and flag sections sequentially.
Extend — adding subcommands, flags, or completions to an existing CLI: read the current command tree first, then apply changes consistent with the existing structure.
Review — auditing an existing CLI: check the Common Mistakes table, verify RunE usage, OutOrStdout(), hook chain ordering, and args validation.
Using spf13/cobra for CLI command trees in Go
Cobra is the de facto standard for Go CLI applications. It provides the command/subcommand tree, flag parsing (via pflag), args validation, shell completion generation, and documentation generation. It does not handle configuration layering — that's viper's job.
This skill is not exhaustive — refer to library documentation and code examples for more information:
For Go package docs, symbols, versions, importers, and known vulnerabilities, → See samber/cc-skills-golang@golang-pkg-go-dev skill (godig), preferred over Context7 for Go package facts.
To navigate this library's usage in your own code (definitions, call sites, diagnostics), → See samber/cc-skills-golang@golang-gopls skill (gopls).
Context7 remains a fallback for docs not indexed on pkg.go.dev.
go get github.com/spf13/cobra@latest
Cobra vs. viper
These libraries do fundamentally different things and can be used independently.
Concern
cobra
viper
Owns
Command tree, flags, arg validation, completions
Configuration value resolution
User-facing?
Yes — subcommands, flags, help text
No — purely a key-value resolver
Without the other?
Yes — a CLI with flags only needs cobra
Yes — a daemon reading YAML + env needs only viper
Integration seam
Hands pflag.Flag to viper via BindPFlag
Treats the cobra flag as the highest-precedence layer
Use cobra alone when your binary takes flags and args but needs no config file or env resolution. Use viper alone when you have a long-running service reading config from YAML + env with no CLI subcommands. Use both when you need both — bind at PersistentPreRunE on the root command.
→ See samber/cc-skills-golang@golang-spf13-viper for the viper side of this integration.
Command tree
Every cobra CLI has a root command plus zero or more subcommands registered with AddCommand. The root command name is the binary name.
var rootCmd = &cobra.Command{
Use: "myapp",
Short: "One-line summary",
SilenceUsage: true, // ✓ prevents usage wall on every error
SilenceErrors: true, // ✓ lets you control error output format
}
Use AddGroup to label subcommands in help output — register groups before the AddCommand calls that reference them; cobra does not retroactively assign groups.
The Run* family
Cobra commands have five run hooks executed in order:
Cobra validates positional arguments before RunE runs. Never write len(args) checks inside RunE — that bypasses cobra's standard error messages and arg count tracking.
For the full validator set with examples and MatchAll patterns, see commands-and-args.md.
Flags primer
Cobra delegates flag parsing to pflag. Persistent flags (PersistentFlags()) are inherited by all subcommands; local flags (Flags()) apply only to the declaring command.
rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file path") // inherited by all subcommands
serveCmd.Flags().IntVar(&port, "port", 8080, "listen port") // local to serveCmd only
serveCmd.MarkFlagRequired("port")
serveCmd.MarkFlagsMutuallyExclusive("json", "yaml")
For pflag types, custom flag values, flag groups, and viper binding, see flags.md.
Completions primer
Cobra generates shell completions automatically. Extend them with:
RegisterFlagCompletionFunc(name, fn) — flag value completion.
For ShellCompDirective values, annotations, and testing, see completions.md.
Testing commands
Test commands by executing them programmatically. Never use os.Stdout / os.Stderr directly in command handlers — use cmd.OutOrStdout() / cmd.ErrOrStderr() so tests can redirect output.
Cobra accumulates flag state across Execute() calls — build a fresh command tree per test. For isolation patterns, golden files, and testing completions, see testing.md.
Best Practices
Always use RunE, never Run — Run cannot return an error; the only escape is os.Exit or panic, bypassing defers.
Put config initialization in PersistentPreRunE — it runs before every subcommand; the right place for viper binding and auth checks.
Validate positional args with Args, not inside RunE — Args gives cobra's standard error messages; MatchAll composes validators.
Use cmd.OutOrStdout() / cmd.ErrOrStderr() for all output — direct os.Stdout writes cannot be captured by tests.
Re-create the command tree per test — cobra accumulates flag state across Execute() calls on the same instance.
Common Mistakes
Mistake
Why it fails
Fix
Using Run instead of RunE
Cannot return an error — only escape is os.Exit or panic, bypassing defers
Use RunE — return the error, let cobra handle the exit
Writing len(args) checks in RunE
Bypasses cobra's standard error messages ("accepts 1 arg, received 2")
Download skills/golang-spf13-cobra/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does golang-spf13-cobra live?
The publisher keeps it at https://github.com/samber/cc-skills-golang.
Which agents can use golang-spf13-cobra?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.