菜单
CLI command tree library for Golang using spf13/cobra — cobra.Command, RunE vs Run, PreRun hooks, Args validators, persistent vs local flags, shell completion, testing via SetArgs. Apply when using/adopting cobra or the codebase imports github.com/spf13/cobra. Config: golang-spf13-viper.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/context-labs/whip --skill golang-spf13-cobra命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| name | golang-spf13-cobra |
| description | CLI command tree library for Golang using spf13/cobra — cobra.Command, RunE vs Run, PreRun hooks, Args validators, persistent vs local flags, shell completion, testing via SetArgs. Apply when using/adopting cobra or the codebase imports github.com/spf13/cobra. Config: golang-spf13-viper. |
| 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.0","openclaw":{"emoji":"🐍","homepage":"https://github.com/samber/cc-skills-golang","requires":{"bins":"[Truncated]"},"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:*) LSP mcp__gopls__* |
| paths | ["**/*.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:
RunE usage, OutOrStdout(), hook chain ordering, and args validation.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.
Official Resources:
This skill is not exhaustive. Please 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) — prefer it 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
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.
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.
Cobra commands have five run hooks executed in order:
PersistentPreRunE → PreRunE → RunE → PostRunE → PersistentPostRunE
Always use *E variants — the non-E forms cannot return errors. Key rules:
PersistentPreRunE on the root runs before every subcommand — use it for config init and auth checks.PersistentPreRunE replaces the parent's entirely — call the parent explicitly if you need both.PostRunE runs only if RunE succeeded.For the full lifecycle and inheritance rules, see commands-and-args.md.
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.
Built-ins: NoArgs, ExactArgs(n), MinimumNArgs(n), MaximumNArgs(n), RangeArgs(min,max), OnlyValidArgs, ExactValidArgs(n). Compose with MatchAll(v1, v2). Custom validator: func(cmd *cobra.Command, args []string) error.
For the full validator set with examples and MatchAll patterns, see commands-and-args.md.
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.
Cobra generates shell completions automatically. Extend them with:
ValidArgs []string — static positional arg completion.ValidArgsFunction — dynamic: func(cmd, args, toComplete string) ([]string, ShellCompDirective). Return ShellCompDirectiveNoFileComp to suppress file fallback.RegisterFlagCompletionFunc(name, fn) — flag value completion.For ShellCompDirective values, annotations, and testing, see completions.md.
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.
func TestServeCmd(t *testing.T) {
buf := new(bytes.Buffer)
rootCmd.SetOut(buf)
rootCmd.SetArgs([]string{"serve", "--port", "9090"})
require.NoError(t, rootCmd.Execute())
assert.Contains(t, buf.String(), "listening on :9090")
}
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.
RunE, never Run — Run cannot return an error; the only escape is os.Exit or panic, bypassing defers.PersistentPreRunE — it runs before every subcommand; the right place for viper binding and auth checks.Args, not inside RunE — Args gives cobra's standard error messages; MatchAll composes validators.cmd.OutOrStdout() / cmd.ErrOrStderr() for all output — direct os.Stdout writes cannot be captured by tests.Execute() calls on the same instance.| 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") | Declare Args: cobra.ExactArgs(1) on the command |
Writing to os.Stdout directly | Tests cannot capture output — os-level file handles can't be redirected | Use cmd.OutOrStdout() / cmd.ErrOrStderr() |
Child PersistentPreRunE silently drops parent's | Cobra does not chain — the child replaces the parent's hook entirely | Call parent.PersistentPreRunE(cmd, args) from the child's hook |
| Reusing a root command across tests | Cobra accumulates flag state; second Execute() sees flags from the first | Build a fresh command tree per test |
cobra-cli scaffoldersamber/cc-skills-golang@golang-cli skill for general CLI architecture — project layout, exit codes, signal handling, I/O patternssamber/cc-skills-golang@golang-spf13-viper skill for configuration layering alongside cobra (flag → env → file → default precedence)samber/cc-skills-golang@golang-testing skill for general Go testing patternsIf you encounter a bug or unexpected behavior in spf13/cobra, open an issue at https://github.com/spf13/cobra/issues.