Go Cobra Applications

Keep Cobra and Viper at the application edge. Construct a fresh command tree per execution and translate CLI state into typed application calls.

Core Workflow

1. Model the tree around user resources, workflows, and operations.
2. Define invocation contracts, argument validation, examples, and flag scope.
3. Construct fresh root and subcommands with explicit dependencies and streams.
4. Keep handlers thin, propagate context, and return errors.
5. Resolve defaults, config, environment, and flags into a validated typed config.
6. Test parsing, inheritance, precedence, help, errors, and repeated execution.
7. Generate completion and documentation from the same runtime tree.

Read Next

| Task | Load | |---|---| | Build or restructure a Cobra application | guidelines.md, workflows/build-cobra-command-tree.md | | Apply command-tree, flag, config, and testing rules | references/cobra-applications/rules.md | | Use constructors and focused implementation examples | references/cobra-applications/examples.md | | Inject services or resolve configuration | references/cobra-applications/patterns.md | | Review a Cobra/Viper application | references/cobra-applications/checklist.md | | Understand architecture, completion, and docs | references/cobra-applications/knowledge.md |

Guardrails

• Avoid mutable package-global commands and init-driven application wiring.
• Domain packages must not import Cobra or Viper.
• Use persistent flags only when descendants genuinely share the option.
• Treat configuration as validated runtime policy, not mutable application storage.
• Validate reload candidates and atomically publish only last-known-good state.
• Show usage for syntax errors, not routine operational failures.
• Verify generator, completion, docs, and configuration APIs against pinned versions.

Source Notes

Guidance is transformed and paraphrased from Ricardo Gerardi, Powerful Command-Line Applications in Go (Pragmatic Bookshelf, 2021), especially Chapter 7. Examples are original adaptations.

Book: https://pragprog.com/titles/rggo/powerful-command-line-applications-in-go/

The book's 2021 generator flow is historical. Verify current APIs and tooling against https://cobra.dev/ and https://github.com/spf13/viper before use.

Suggestion, remote configuration, and live-reload guidance also incorporates transformed material from Marian Montagnino, Building Modern CLI Applications in Go (Packt, 2023), especially Chapter 4.

Parser-boundary guidance also incorporates transformed material from Inanc Gumus, Go by Example: Programmer's Guide to Idiomatic and Testable Programs (Manning, 2025), Chapter 4.