# Golang Spf13 Cobra

> Build, extend, or test Go command trees when `github.com/spf13/cobra` is already used or explicitly selected. Covers command hooks, argument validators, local and persistent flags, completions, injected I/O, and isolated command tests; use a general CLI skill for framework-independent behavior.

- Skill: `reagin/golang-spf13-cobra` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add reagin/golang-spf13-cobra`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reagin/golang-spf13-cobra/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: reagin (https://skillmd.com/u/reagin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/reagin/golang-spf13-cobra

---


# Cobra command trees

Preserve the CLI's public contract: command paths, flags, arguments, output streams, help, completion, exit behavior, and compatibility.

## Inspect before editing

Check `go.mod`, root-command construction, `Execute`/`ExecuteContext`, parent and child hooks, flags, argument validators, I/O, exit-code mapping, completions, generated docs, and tests. Prefer local command factories and helpers over introducing a parallel structure.

## Command execution

- Use `RunE` and `*E` hooks when the handler can fail and the caller should receive the error. `Run` remains valid for genuinely infallible behavior.
- Keep parsing and structural argument checks in Cobra's validation facilities when that improves help and diagnostics. Domain validation that requires loaded state can remain in the handler.
- Return errors from command code instead of calling `os.Exit`; let the outermost executable choose rendering and exit status. Preserve any established typed-error or silence policy.
- Pass `cmd.Context()` into cancellable work. Do not replace it with `context.Background()` inside a command.

Do not assume every ancestor persistent hook runs. Child hooks and the selected traversal behavior affect inheritance. Inspect the pinned version and test the actual order before moving initialization into a parent hook.

## Flags and configuration

Distinguish local and persistent flags and check for inherited-name collisions. Preserve shorthand, defaults, deprecation, requiredness, normalization, and help text as user-facing API.

Read values from the command's flag set or the project's injected configuration object. When integrating Viper, bind flags before any lookup or decode that depends on them; the correct location follows the construction and loading order.

For the concrete hook sequence, built-in validators, flag APIs, completion directives, and an isolated test fixture, read [references/api-and-testing.md](references/api-and-testing.md).

## Change the public surface coherently

When adding or changing a command, update its `Use`, `Short`/`Long`, `Example`, argument validator, flags, completion, and tests as one contract. Keep aliases, hidden/deprecated status, command groups, and inherited flags stable unless the CLI change calls for them. Ensure the executable boundary renders a returned error once and maps it to the established exit status.

Review `SilenceUsage` and `SilenceErrors` together with that outer error-rendering policy; changing only one can duplicate output or hide useful usage.

## I/O, help, and completion

Use `cmd.OutOrStdout()`, `cmd.ErrOrStderr()`, and `cmd.InOrStdin()` in handlers that should respect Cobra's configured streams. Keep diagnostic and machine-readable output on their documented channels.

Completion functions should be fast, cancellation-aware, and free of surprising mutations. Keep ordinary command output out of completion responses and preserve the selected shell directives.

If documentation or completion artifacts are generated, use the repository's existing generation command and review the diff for deterministic output.

## Testing and verification

Prefer constructing a fresh command tree per test; Cobra command and flag objects retain parse state across executions. Set arguments, context, and in-memory streams explicitly, then assert returned errors and output separately. Avoid testing production behavior through process-global `os.Args` or `os.Stdout` unless the executable boundary itself is under test.

Cover parent/child hook order, cancellation, argument validation, flag precedence, output channels, completion, and exit mapping affected by the change. Run formatting and relevant tests, then manually inspect changed help text for public CLI changes.

## Official references

- [Cobra package documentation](https://pkg.go.dev/github.com/spf13/cobra)
- [Cobra documentation](https://cobra.dev/)
- [Cobra repository](https://github.com/spf13/cobra)