[go-fan] Go Module Review: spf13/cobra

[github-actions]

🐹 Go Fan Report: spf13/cobra

Module Overview

github.com/spf13/cobra v1.10.2 is the CLI framework powering the awmg binary. It handles command parsing, flag management, shell completion, subcommand routing, argument validation, and help generation.

Current Usage in gh-aw

The project uses cobra extensively and well across 15 files in internal/cmd/. The usage is sophisticated and leverages many advanced features.

• Files: 15 files in internal/cmd/
• Import Count: 10 production imports + 5 test imports
• Key APIs Used:
  • cobra.Command (root + proxy + completion subcommands)
  • All major flag types: StringVar, BoolVar, IntVar, Float64Var, CountVarP, StringSliceVar
  • MarkFlagsMutuallyExclusive, MarkFlagsOneRequired, MarkFlagRequired
  • cobra.MatchAll, cobra.ExactArgs, cobra.OnlyValidArgs
  • cobra.FixedCompletions, cobra.AppendActiveHelp
  • cmd.Flags().Changed() for CLI-vs-env-var priority logic
  • Full shell completion (bash/zsh/fish/powershell)
  • cmd.Context() for signal-based graceful shutdown

Research Findings

Architecture Highlights

The project implements an elegant modular FlagRegistrar pattern where each flags_*.go file registers its own flags via init(), avoiding merge conflicts when new flags are added. This is a clean, scalable cobra pattern not often seen in the wild.

Best Practices Already Implemented ✅

• SilenceUsage: true — no help spam on runtime errors
• SilenceErrors: true — errors handled explicitly in Execute()
• SetErrPrefix for branded error messages
• cmd.Flags().Changed() to distinguish CLI flags from env-var defaults
• Enum flags use cobra.FixedCompletions for typed shell completions
• cobra.AppendActiveHelp for contextual hints
• DisableFlagsInUseLine: true on completion command
• cobra.MatchAll + cobra.ExactArgs + cobra.OnlyValidArgs for airtight arg validation
• PersistentPreRunE for validation, PersistentPostRun for cleanup

Improvement Opportunities

🏃 Quick Wins

1. Add Args: cobra.NoArgs to root command

The root command currently accepts positional arguments silently. If a user types awmg config.toml instead of awmg --config config.toml, they get a cryptic "required flag(s) not set" error rather than a helpful message. Adding Args: cobra.NoArgs gives a clear error: unknown command "config.toml" for "awmg".

var rootCmd = &cobra.Command{
    Use:  "awmg",
    Args: cobra.NoArgs,  // ← add this
    // ...
}

2. Simplify file/directory flag completions using MarkFlagFilename/MarkFlagDirname

The current registerFlagCompletions in flags.go uses verbose RegisterFlagCompletionFunc calls for file extension and directory completions. Cobra provides idiomatic shorthands that do the same thing more concisely:

// Instead of (current):
cmd.RegisterFlagCompletionFunc("config", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
    return []string{"toml"}, cobra.ShellCompDirectiveFilterFileExt
})
cmd.RegisterFlagCompletionFunc("log-dir", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
    return nil, cobra.ShellCompDirectiveFilterDirs
})

// Use instead:
cmd.MarkFlagFilename("config", "toml")
cmd.MarkFlagDirname("log-dir")
cmd.MarkFlagDirname("payload-dir")
cmd.MarkFlagFilename("env", "env")

This reduces ~24 lines of completion boilerplate to 4 lines.

3. Fix fragile preRun(nil, nil) in tests

root_test.go calls preRun(nil, nil) in several test cases. While this works today (preRun doesn't dereference cmd), it's fragile — any future change that uses cmd.Context() or another method will cause a nil pointer panic. The fix is one line:

// Instead of:
err := preRun(nil, nil)

// Use:
err := preRun(newTestCmd(), nil)

✨ Feature Opportunities

1. Add Example field to commands

The root command and proxy command put examples in the Long description (which works), but cobra has a dedicated Example field that gets its own formatted "Examples:" section in help output. This improves discoverability and is the idiomatic cobra pattern:

var rootCmd = &cobra.Command{
    Use:   "awmg",
    Short: "MCPG MCP proxy server",
    Long:  `...`,
    Example: `  # Start in routed mode with a config file
  awmg --config config.toml --routed

  # Start in unified mode reading config from stdin
  cat config.json | awmg --config-stdin --unified --listen 0.0.0.0:3000`,
}

2. Command groups for subcommands

With completion and proxy subcommands, the help output lists them together. Using AddGroup (available since cobra v1.6.0) lets you organize them under labeled headings:

rootCmd.AddGroup(&cobra.Group{
    ID:    "modes",
    Title: "Operation Modes:",
})
rootCmd.AddGroup(&cobra.Group{
    ID:    "utils",
    Title: "Utilities:",
})
proxyCmd.GroupID = "modes"
completionCmd.GroupID = "utils"

📐 Best Practice Alignment

1. Document proxy flag duplication rationale

proxy.go re-declares --listen (different default: 127.0.0.1:8080 vs 127.0.0.1:3000) and --log-dir flags that the root command already has. A comment explaining why these are independent (different purposes, different defaults) would help future contributors avoid accidentally making them persistent flags.

2. Comment on PersistentPreRunE override in completion command

completion.go sets cmd.PersistentPreRunE = func(...) { return nil } to skip root's validation hook. A short comment explaining that cobra doesn't chain PersistentPreRunE automatically (unlike, say, middleware) would prevent future confusion.

Recommendations (Prioritized)

1. [P1 — Quick, safe] Add Args: cobra.NoArgs to root command — one line, prevents confusing UX
2. [P2 — Refactor] Simplify file/dir completion functions with MarkFlagFilename/MarkFlagDirname
3. [P2 — Robustness] Replace preRun(nil, nil) with preRun(newTestCmd(), nil) in tests
4. [P3 — Polish] Add Example field to root and proxy commands
5. [P3 — Polish] Consider AddGroup for subcommand categorization in help output

Next Steps

• Items 1–3 are good candidates for a small cleanup PR
• Items 4–5 are polish and can be deferred

---

Generated by Go Fan 🐹
Module summary saved to: /tmp/gh-aw/agent/cobra.md (repo is read-only in this environment)
Run: §24823152183

Note

🔒 Integrity filter blocked 11 items

The following items were blocked because they don't meet the GitHub integrity level.

• search_repositories search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/santhosh-tekuri/jsonschema search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/spf13/cobra search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/open-telemetry/opentelemetry-go search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/golang/term search_repositories: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/spf13/cobra/releases/tag/v1.10.2 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/santhosh-tekuri/jsonschema/releases/tag/v6.0.2 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/open-telemetry/opentelemetry-go/releases/tag/v1.43.0 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• https://github.com/wazero/wazero/releases/tag/v1.11.0 list_releases: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• get_file_contents get_file_contents: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".
• list_tags list_tags: has lower integrity than agent requires. The agent cannot read data with integrity below "unapproved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Go Fan · ● 1.3M · ◷

• expires on Apr 30, 2026, 7:47 AM UTC