Skip to content

cobra.md

Latest commit

 

History

History
137 lines (106 loc) · 12.8 KB

cobra.md

File metadata and controls

137 lines (106 loc) · 12.8 KB

Cobra

Overview

  • Version: 1.8.x (1.8.1 as of mid-2024)
  • Language: Go
  • License: Apache-2.0
  • Maintainer: spf13 (Steve Francia) + community; used internally by major organizations
  • Maintenance Status: Actively maintained; regular releases; widely used in production (kubectl, Helm, Hugo, GitHub CLI, Docker CLI all use Cobra)
  • GitHub Stars: ~38,000 (as of mid-2025)
  • Go Module: github.com/spf13/cobra
  • Companion library: Viper (github.com/spf13/viper) for configuration management, commonly used alongside Cobra
  • Knowledge Cutoff Note: Reflects Cobra 1.8.x; post mid-2025 changes not covered.

Architecture & Design

Cobra models CLIs as a tree of *cobra.Command structs. Each command has:

  • Use, Short, Long: name, one-line description, full description
  • RunE / Run: the execution function (RunE returns an error, preferred)
  • Args: built-in argument validators (cobra.ExactArgs(n), cobra.MinimumNArgs(n), cobra.MatchAll(...))
  • PreRunE / PostRunE: lifecycle hooks for setup/teardown
  • PersistentPreRunE: inherited by all subcommands — ideal for auth, config loading
  • Flags via pflag (POSIX-compliant, supports shorthand and long form)

Viper integration: Cobra commands commonly bind flags to Viper keys via viper.BindPFlag(). Viper enforces a layered precedence: explicit flag > env var > config file > default. This is the closest any of the evaluated frameworks gets to a principled config-precedence model.

Shell completion: Cobra generates completion scripts for bash, zsh, fish, and PowerShell natively. Completion for dynamic values is supported via ValidArgsFunction.

Code generation: cobra-cli (the companion generator) scaffolds command files; not relevant to agent use but indicates ecosystem maturity.

Error handling: RunE returning a non-nil error causes Cobra to print the error to stderr and exit non-zero. The exit code is 1 by default; cobra.Command.SilenceErrors and SilenceUsage control whether usage is reprinted on error.

Annotations: Command.Annotations is a map[string]string that can carry arbitrary metadata — useful for marking commands as destructive, hidden from agents, etc., though no standard convention exists.

Agent Compatibility Assessment

What it handles natively

  • Exit codes: RunE errors → exit 1; argument validation errors → distinct exit path; os.Exit(n) works freely. More disciplined than Python frameworks.
  • Stderr vs stdout: Errors go to cmd.ErrOrStderr() (defaults to os.Stderr); normal output to cmd.OutOrStdout(). SilenceUsage=true prevents usage text from polluting stderr on errors.
  • Argument validation: Built-in validators run before Run/RunE. Custom validators via cobra.MatchAll or custom Args functions. Validation failures produce clear messages.
  • Help discoverability: --help on every command; help [command] subcommand; structured via Command.UsageTemplate() and Command.HelpTemplate() (customizable).
  • Shell completion: Four shells supported natively; ValidArgsFunction enables dynamic completion — machine-readable list of valid values.
  • Config precedence with Viper: Flag > env > config file > default; AutomaticEnv() maps env vars; prefix-based env namespacing.
  • PersistentPreRunE: Single place for auth, config loading, and environment validation across all subcommands.
  • SilenceErrors/SilenceUsage: Prevents help text from being emitted to stderr on every error, which would break stream parsing.

What it handles partially

  • Output format: No built-in JSON/YAML mode; but the ecosystem norm (kubectl, Helm, GitHub CLI) is to implement --output/-o json manually. Common enough that agent callers have learned to look for it.
  • Structured errors: Errors are Go error interface strings; no machine-readable error taxonomy beyond exit code.
  • Signal handling: Go's os/signal works; Cobra has no built-in context-with-cancel threading through commands. Applications must wire context.WithCancel and signal.NotifyContext manually.
  • Verbosity: No built-in flag; each app must add --verbose/--quiet. Persistent flags can propagate these to subcommands.

What it does not handle

  • Timeouts: No built-in command timeout; application must use context.WithTimeout.
  • Structured output: No JSON output primitives in the framework.
  • Idempotency: No framework support.
  • Retry hints: No structured retry metadata.
  • Observability: No built-in tracing/audit; must use external libraries.
  • Self-update: No built-in; selfupdate libraries exist but are not Cobra-native.
  • Prompt injection defense: No output sanitization.
  • Schema versioning: No output schema versioning.

Challenge Coverage Table

# Challenge Rating Reason
1 Exit Codes & Status Signaling ~ RunE → exit 1 for errors; argument validation → exit 1; but no taxonomy beyond 0/1 enforced by framework; os.Exit(n) available but requires developer discipline.
2 Output Format & Parseability ~ No built-in JSON mode; but ecosystem convention (kubectl, gh) is strong enough that agents often assume --output json exists on well-maintained Cobra tools.
3 Stderr vs Stdout Discipline ✓ cmd.ErrOrStderr() / cmd.OutOrStdout() separation enforced; SilenceUsage=true prevents usage text on stderr; errors routed correctly by default.
4 Verbosity & Token Cost ~ No built-in levels; persistent flags can propagate --verbose; no framework-level log-level integration.
5 Pagination & Large Output ✗ No pagination API; applications must implement; no chunked-output streaming primitives.
6 Command Composition & Piping ~ Tree-of-commands model composes well; stdin reading via os.Stdin; no pipeline DSL.
7 Output Non-Determinism ✗ No framework controls for output ordering; Go map iteration is randomized by design — apps must sort explicitly.
8 ANSI & Color Code Leakage ~ No built-in TTY detection in Cobra itself; applications often use isatty package; cobra.Command does not strip ANSI automatically.
9 Binary & Encoding Safety ✓ Go's os.Stdout is a byte stream; UTF-8 by default; no encoding ambiguity; binary-safe if app uses os.Stdout.Write() directly.
10 Interactivity & TTY Requirements ~ No built-in prompting; apps use third-party survey/prompt libraries; no framework-level default-when-non-TTY logic.
11 Timeouts & Hanging Processes ~ context.WithTimeout integrates cleanly with RunE's context parameter (Cobra 1.5+ passes context); but wiring is app responsibility.
12 Idempotency & Safe Retries ✗ No framework support.
13 Partial Failure & Atomicity ✗ No transaction primitives; PostRunE can do cleanup but no built-in rollback.
14 Argument Validation Before Side Effects ✓ Args validators and PersistentPreRunE run before RunE; type-safe via pflag; validation failures exit before business logic.
15 Race Conditions & Concurrency ✗ No locking primitives; concurrent command execution is application concern.
16 Signal Handling & Graceful Cancellation ~ signal.NotifyContext pairs with Cobra's context threading; PreRunE can set up signal handlers; not built into framework but idiomatic Go pattern is clean.
17 Child Process Leakage ✗ No subprocess lifecycle management; apps must use exec.CommandContext with the command's context to avoid leaks.
18 Error Message Quality ~ RunE error strings printed to stderr with Error: prefix; quality depends on developer; pflag flag errors are well-formatted.
19 Retry Hints in Error Responses ✗ No structured retry metadata; error is a string on stderr and exit code 1.
20 Environment & Dependency Discovery ~ Viper's AutomaticEnv + SetEnvPrefix provides env mapping; no dependency health-check framework; PersistentPreRunE is a natural place but not enforced.
21 Schema & Help Discoverability ~ --help on every command; cobra-doc can generate markdown/man pages/YAML docs (cmd.GenYamlTree()); YAML doc generation is machine-parseable — significant advantage.
22 Schema Versioning & Output Stability ~ No output schema versioning; but GenYamlTree / GenMarkdownTree document interfaces in a stable format; help template is customizable and stable if frozen.
23 Side Effects & Destructive Operations ~ Annotations map can mark commands as destructive; no built-in confirmation prompt; apps must implement.
24 Authentication & Secret Handling ~ Viper reads secrets from env vars with prefix; no secret-store integration; flags marked sensitive won't appear in completion but may appear in --help.
25 Prompt Injection via Output ✗ No output sanitization; command output echoed verbatim.
26 Stateful Commands & Session Management ✗ No cross-invocation session management; each invocation is stateless.
27 Platform & Shell Portability ✓ Go produces static binaries; cross-compilation is native; works on Linux/macOS/Windows without runtime dependencies; shell completion covers bash/zsh/fish/PowerShell.
28 Config File Shadowing & Precedence ✓ Viper enforces: flag > env > config file > default; multiple config formats (JSON/YAML/TOML); SetConfigFile and AddConfigPath for discovery.
29 Working Directory Sensitivity ~ No cwd enforcement; filepath.Abs() available; apps must call it explicitly.
30 Undeclared Filesystem Side Effects ✗ No declarative side-effect manifest.
31 Network Proxy Unawareness ~ Go's http.ProxyFromEnvironment respects HTTP_PROXY/HTTPS_PROXY/NO_PROXY by default in the standard http.Client; but only if the app uses the default transport.
32 Self-Update & Auto-Upgrade Behavior ✗ No built-in; third-party go-selfupdate or similar must be wired manually.
33 Observability & Audit Trail ~ No built-in; but Go's structured logging ecosystem (slog, zap, zerolog) integrates cleanly; PersistentPreRunE can initialize a logger; no framework-level hook.

Summary: Native ✓: 5 | Partial ~: 17 | Missing ✗: 11

Strengths for Agent Use

  1. Stderr/stdout discipline is enforced by convention: cmd.ErrOrStderr() and SilenceUsage=true are idiomatic and widely followed, making stream parsing reliable on well-maintained Cobra tools.
  2. Pre-execution validation: Args validators and PersistentPreRunE run before business logic; agent can distinguish arg-error from runtime-error.
  3. Static binary distribution: No runtime dependencies to manage; cross-platform; agents can invoke Cobra binaries without environment setup.
  4. YAML/Markdown doc generation: cobra-doc / GenYamlTree provides machine-parseable command documentation — unique among the evaluated frameworks.
  5. Viper config precedence: The layered config model (flag > env > file > default) is explicit and predictable for agent configuration injection.
  6. Context threading: Cobra 1.5+ threads context.Context through commands, enabling clean timeout and cancellation wiring.
  7. Ecosystem norms: Major tools (kubectl, Helm, gh, Docker) set strong conventions; agents that work with those tools have established patterns.

Weaknesses for Agent Use

  1. No structured output by default: Every tool must independently implement --output json; no framework enforcement.
  2. Go map non-determinism: Developers must explicitly sort map outputs; easy to forget, leading to non-deterministic output.
  3. No timeout enforcement: context.WithTimeout is available but must be wired manually per command.
  4. Exit code taxonomy: Only 0/1 enforced; no standard codes for "user error" vs "system error" vs "transient failure".
  5. ANSI not stripped: TTY detection is app responsibility; many Cobra tools emit color codes to agents.

Verdict

Cobra is the strongest of the evaluated frameworks for agent compatibility, not because it was designed with agents in mind, but because its design decisions — separated streams, pre-execution validation, static binaries, context threading, and Viper's layered config — align well with agent requirements. The widespread adoption by major infrastructure tools (kubectl, Helm, GitHub CLI) has also created de facto conventions (like --output json) that agents can exploit. Its primary weaknesses are the absence of structured output primitives and a rich exit-code taxonomy, both of which require per-application implementation. For an agent operator building tooling, Cobra is the recommended foundation among the frameworks evaluated here; for an agent consumer facing existing Cobra tools, reliability of parsing depends heavily on the individual tool's adherence to ecosystem conventions.