golang-spf13-cobra
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 golang-spf13-viper. For general CLI architecture, see golang-cli.
- License 许可
- MIT
- 最近更新
- 2026-08-26
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- golang-spf13-cobra
- license
- MIT
- metadata
- { "author": "gentleman-programming", "version": "1.0.0", "openclaw": { "emoji": "🐍", "install": [], "homepage": "https://github.com/gentleman-programming", "requires": { "bins": [ "go" ] } } }
- 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 golang-spf13-viper. For general CLI architecture, see golang-cli.
- allowed-tools
- Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent WebFetch
- compatibility
- Designed for OpenCode or similar AI coding agents, and for projects using Golang.
- user-invocable
- true
02 资源文件 6
- 参考文档evals/evals.json19.1 KB
- 参考文档references/commands-and-args.md2.4 KB
- 参考文档references/completions.md3.9 KB
- 参考文档references/flags.md2.5 KB
- 参考文档references/generators.md2.2 KB
- 参考文档references/testing.md3.7 KB
03 SKILL.md 正文
Persona: Sos un engineer de CLI en Go que construye árboles de comandos que se sienten nativos en la shell Unix. Diseñás la superficie orientada al usuario primero, y después cableás el comportamiento en el hook correcto.
Modos:
- Build — creando una CLI desde cero: seguí command tree setup, hook wiring y flag sections en orden.
- Extend — agregando subcomandos/flags/completions a una CLI existente: leé el árbol actual primero.
- Review — auditando una CLI: chequeá la tabla de Common Mistakes, verificá
RunE,OutOrStdout(), orden de hooks y args validation.
Using spf13/cobra for CLI command trees in Go
Cobra es el estándar de facto para CLIs en Go. Provee el árbol command/subcommand, parseo de flags (vía pflag), validación de args, generación de shell completions y documentación. No maneja config layering — eso es trabajo de viper.
Official Resources:
go get github.com/spf13/cobra@latest
Cobra vs. viper
Estas libs hacen cosas fundamentalmente distintas y pueden usarse por separado.
| Concern | cobra | viper |
|---|---|---|
| Owns | Árbol de comandos, flags, arg validation, completions | Resolución de valores de config |
| User-facing? | Sí — subcomandos, flags, help | No — solo un key-value resolver |
| Integration seam | Pasa pflag.Flag a viper vía BindPFlag |
Trata el flag de cobra como la capa de mayor precedencia |
Usá cobra solo cuando tu binario toma flags/args pero no necesita config file ni env. Usá viper solo para un daemon que lee YAML + env sin subcomandos. Usá ambos cuando los necesites — bindealos en PersistentPreRunE del root command.
→ See golang-spf13-viper para el lado viper de esta integración.
Command tree
Cada CLI cobra tiene un root command más cero o más subcomandos registrados con AddCommand.
var rootCmd = &cobra.Command{
Use: "myapp",
Short: "One-line summary",
SilenceUsage: true, // ✓ previene el usage wall en cada error
SilenceErrors: true, // ✓ dejás vos el formato del error
}
Usá AddGroup para etiquetar subcomandos en el help — registrá los groups antes de los AddCommand que los referencian.
The Run* family
Cobra tiene cinco run hooks ejecutados en orden:
PersistentPreRunE → PreRunE → RunE → PostRunE → PersistentPostRunE
Siempre usá variantes *E — las formas sin E no pueden retornar error. Reglas clave:
PersistentPreRunEen el root corre antes de cada subcommand — usalo para config init y auth checks.- Un
PersistentPreRunEhijo reemplaza al del parent — llamalo explícitamente si necesitás ambos. PostRunEcorre solo siRunEtuvo éxito.
For the full lifecycle, see commands-and-args.md.
Args validators
Cobra valida args posicionales antes de RunE. NUNCA escribas checks de len(args) dentro de RunE — eso bypassa los mensajes estándar de cobra.
Built-ins: NoArgs, ExactArgs(n), MinimumNArgs(n), MaximumNArgs(n), RangeArgs(min,max), OnlyValidArgs, ExactValidArgs(n). Componé con MatchAll(v1, v2). Custom validator: func(cmd *cobra.Command, args []string) error.
Flags primer
Cobra delega el parseo a pflag. Persistent flags (PersistentFlags()) se heredan a todos los subcomandos; local flags (Flags()) solo al comando que los declara.
rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file path")
serveCmd.Flags().IntVar(&port, "port", 8080, "listen port")
serveCmd.MarkFlagRequired("port")
serveCmd.MarkFlagsMutuallyExclusive("json", "yaml")
For pflag types, custom flag values y viper binding, see flags.md.
Completions primer
Cobra genera shell completions automáticamente. Extendelas con:
ValidArgs []string— completión estática de args posicionalesValidArgsFunction— dinámica:func(cmd, args, toComplete string) ([]string, ShellCompDirective)RegisterFlagCompletionFunc(name, fn)— completión de valores de flags
For ShellCompDirective values, see completions.md.
Testing commands
Testeá comandos ejecutándolos programáticamente. NUNCA uses os.Stdout/os.Stderr directamente en los handlers — usá cmd.OutOrStdout()/cmd.ErrOrStderr() para que los tests redirijan.
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 acumula flag state entre Execute() calls — construí un árbol fresco por test.
Best Practices
- Siempre
RunE, nuncaRun—Runno puede retornar error - Config init en
PersistentPreRunE— corre antes de cada subcommand - Validá args posicionales con
Args, no dentro deRunE—Argsda los mensajes estándar de cobra - Usá
cmd.OutOrStdout()/cmd.ErrOrStderr()para todo output —os.Stdoutno se captura en tests - Re-creá el árbol de comandos por test — cobra acumula flag state
Common Mistakes
| Mistake | Why it fails | Fix |
|---|---|---|
Run en vez de RunE |
No puede retornar error | Usá RunE |
len(args) checks en RunE |
Bypassa los mensajes estándar de cobra | Declarás Args: cobra.ExactArgs(1) |
Escribir a os.Stdout directo |
Tests no capturan | cmd.OutOrStdout() |
PersistentPreRunE hijo tira el del parent |
Cobra no encadena | Llamá al parent explícitamente |
| Reusar root entre tests | Cobra acumula flag state | Árbol fresco por test |
Further Reading
- commands-and-args.md — PreRun*/PostRun* chain, todos los Args validators, reglas de herencia
- flags.md — pflag types, required/exclusive groups, custom value types, viper binding
- completions.md — ShellCompDirective, anotaciones, testing completions
- generators.md — man page, markdown, YAML doc gen;
cobra-cliscaffolder - testing.md — isolation patterns, golden files
Cross-References
- → See golang-cli para arquitectura general de CLI (layout, exit codes, signal handling, I/O)
- → See golang-spf13-viper para config layering (flag → env → file → default)
- → See golang-testing para patrones generales de testing en Go
If you find a bug in spf13/cobra, open an issue at https://github.com/spf13/cobra/issues.
04 同仓库更多 Skills
zustand-5
Zustand 5 state management patterns. Trigger: When managing React state with Zustand.
zod-4
Zod 4 schema validation patterns. Trigger: When using Zod for validation - breaking changes from v3.
x-bookmark-quote-posts
Workflow para revisar bookmarks de X/Twitter y convertirlos en drafts de quote posts. Accede a la sección de bookmarks vía browser headless, extrae posts recientes, y genera drafts con voz personal del usuario. No publica ni muta X — solo genera contenido para revisión. Trigger: X bookmarks, Twitter bookmarks, quote posts, bookmark automation, crear quote posts, revisar bookmarks, growth content X.
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
work-unit-commits
Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.