Skip to content

carapace-sh/carapace-bin / skills/cobra

Use when building CLI applications with spf13/cobra — creating commands, defining flags, argument validation, lifecycle hooks, help/usage customization, shell completions, or Viper integration. Triggers on: "cobra", "cobra command", "cobra flag", "cobra subcommand", "cobra completion", "cobra help", "cobra usage", "cobra hook", "cobra viper", "AddCommand", "PersistentFlags", "LocalFlags", "MarkFlagRequired", "RunE", "PreRun", "PostRun", "PersistentPreRun", "ValidArgs", "ValidArgsFunction", "RegisterFlagCompletionFunc", "ShellCompDirective", "ExactArgs", "NoArgs", "MinimumNArgs", "MatchAll", "MarkFlagsRequiredTogether", "MarkFlagsMutuallyExclusive", "cobra-cli", "cobra completion", "cobra active help", "cobra plugin".

FileKindSize
SKILL.mdskill md4.2 KB
references/arguments.mdmarkdown3.5 KB
references/commands.mdmarkdown6.4 KB
references/completions.mdmarkdown7.5 KB
references/flags.mdmarkdown6.3 KB
references/help-usage.mdmarkdown4.5 KB
references/hooks.mdmarkdown4.9 KB
references/viper-integration.mdmarkdown4.0 KB

references/viper-integration.md

View on GitHub
# Viper Integration

How to integrate cobra with [viper](https://github.com/spf13/viper) for 12-factor application configuration.

## The Pattern

Cobra handles the CLI surface. Viper handles configuration from files, environment variables, and remote sources. The bridge is `BindPFlag` and `OnInitialize`.

## OnInitialize

Register a config initialization function that runs before every command:

```go
var cfgFile string

func init() {
    cobra.OnInitialize(initConfig)
    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.app.yaml)")
}

func initConfig() {
    if cfgFile != "" {
        viper.SetConfigFile(cfgFile)
    } else {
        home, _ := os.UserHomeDir()
        viper.AddConfigPath(home)
        viper.SetConfigName(".app")
        viper.SetConfigType("yaml")
    }
    viper.AutomaticEnv()
    if err := viper.ReadInConfig(); err == nil {
        fmt.Println("Using config file:", viper.ConfigFileUsed())
    }
}
```

## Binding Flags to Viper

```go
rootCmd.PersistentFlags().StringP("author", "a", "YOUR NAME", "author name")
viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
```

After binding, `viper.GetString("author")` returns the flag value (if set) or the config file value (if set) or the default.

## Precedence Order

Viper resolves values in this order (highest wins):

1. **Flag value** (explicitly set on command line)
2. **Environment variable** (if `viper.AutomaticEnv()` is called)
3. **Config file value**
4. **Default value** (from `SetDefault` or flag default)

## Full Integration Example

```go
package cmd

import (
    "fmt"
    "os"
    "github.com/spf13/cobra"
    "github.com/spf13/viper"
)

var cfgFile string
var author string

var rootCmd = &cobra.Command{
    Use:   "app",
    Short: "My application",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("author:", viper.GetString("author"))
    },
}

func init() {
    cobra.OnInitialize(initConfig)

    rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file")
    rootCmd.PersistentFlags().StringP("author", "a", "YOUR NAME", "author name")
    viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
    viper.SetDefault("author", "unknown")
}

func initConfig() {
    if cfgFile != "" {
        viper.SetConfigFile(cfgFile)
    } else {
        home, _ := os.UserHomeDir()
        viper.AddConfigPath(home)
        viper.SetConfigType("yaml")
        viper.SetConfigName(".app")
    }
    viper.AutomaticEnv()
    if err := viper.ReadInConfig(); err == nil {
        fmt.Println("Using config file:", viper.ConfigFileUsed())
    }
}

func Execute() error {
    return rootCmd.Execute()
}
```

## Environment Variable Binding

`viper.AutomaticEnv()` makes viper check environment variables. By default, it maps config keys to env vars by uppercasing and replacing `.` with `_`:

```go
// Config key: "database.host"
// Env var:    DATABASE_HOST
```

Use `viper.BindEnv("database.host", "DB_HOST")` for custom mappings.

## Edge Cases

- **Bound variable vs viper.Get**: When you use `StringVar` with `BindPFlag`, the Go variable is set by pflag during flag parsing. But if the user doesn't provide the flag, the variable gets the pflag default — **not** the viper config value. Always use `viper.GetString()` to get the merged value.
- **Config file errors**: `ReadInConfig()` returns an error if the config file exists but can't be parsed. Check `err != nil` and handle appropriately.
- **OnInitialize timing**: `OnInitialize` functions run in `ExecuteC()` before command resolution. They run on every execution, even for completions and help.
- **Multiple config paths**: `AddConfigPath` can be called multiple times. Viper searches paths in reverse order (last added = first searched).

## References

- [viper documentation](https://github.com/spf13/viper)
- [cobra user guide: viper integration](https://github.com/spf13/cobra/blob/main/site/content/user_guide.md)

## Related Skills

- For `OnInitialize` internals, see the **cobra-dev** skill → `references/global-state.md`.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall