Cobra

Cobra allows you to execute functions before or after the main Run function of a command. These hooks follow a specific execution order and have different inheritance behaviors:

Execution Order:

1. PersistentPreRun
2. PreRun
3. Run
4. PostRun
5. PersistentPostRun

Key Behaviors:

• Inheritance: PersistentPreRun and PersistentPostRun are inherited by child commands if the child does not declare its own. PreRun and PostRun are local to the command and are not inherited.
• Requirement: *PreRun and *PostRun functions are only executed if the command has a Run function declared.
• Traversal: By default, only the first persistent hook found in the command chain is executed. If you want to execute all parents' persistent hooks, set the global variable EnableTraverseRunHooks = true.

package main

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

func main() {
  var rootCmd = &cobra.Command{
    Use:   "root [sub]",
    PersistentPreRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside rootCmd PersistentPreRun\n")
    },
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside rootCmd Run\n")
    },
  }

  var subCmd = &cobra.Command{
    Use: "sub",
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside subCmd Run\n")
    },
  }

  rootCmd.AddCommand(subCmd)
  rootCmd.Execute()
}

Cobra supports a legacy dynamic completion solution specifically for the Bash shell. This is used to inject custom Bash functions into the completion script to provide dynamic choices.

Important Considerations:

• This solution is only compatible with Bash; it will not work for other shells.
• It can coexist with the newer ValidArgsFunction and RegisterFlagCompletionFunc() as long as they are not used for the same command.
• Warning: Cobra's default completion command uses Bash completion V2. If you rely on this legacy solution, do not use the default completion command; continue using your own custom completion script.

To implement this, you define a string containing Bash functions and assign it to the BashCompletionFunction field of your cobra.Command (typically on the root command).

cmds := &cobra.Command{
	Use:   "kubectl",
	Short: "kubectl controls the Kubernetes cluster manager",
	Run:   runHelp,
	BashCompletionFunction: bash_completion_func, // string containing Bash function definitions
}

Cobra 1.1 deprecated several Zsh-specific methods in favor of a unified ValidArgsFunction approach. If you are using older versions, you should migrate to avoid silent ignores.

Deprecated Positional Argument Methods

• cmd.MarkZshCompPositionalArgumentFile(pos, []string{}): Deprecated. File completion is now enabled by default for all arguments. To disable it for a specific argument, use ValidArgsFunction with ShellCompDirectiveNoFileComp.
• cmd.MarkZshCompPositionalArgumentFile(pos, glob[]): Deprecated. To filter by file extension instead of full globbing, use ValidArgsFunction with ShellCompDirectiveFilterFileExt.
• cmd.MarkZshCompPositionalArgumentWords(pos, words[]): Deprecated. Use ValidArgsFunction to provide specific completion choices for a positional argument.

Summary of Behavioral Changes

Cobra uses ShellCompDirectiveDefault by default, which invokes the shell's filename completion. If a command or flag does not operate on filenames, you should disable file completion to avoid incorrect suggestions.

Ways to manage directives:

• Disable file completion for a specific flag: Use cobra.NoFileCompletions in a completion function.
• Recursively disable file completion for a command and all subcommands: Use cmd.CompletionOptions.SetDefaultShellCompDirective(ShellCompDirectiveNoFileComp).
• Re-enable file completion for specific leaf commands/flags: Use cobra.FixedCompletions(nil, ShellCompDirectiveDefault) within a completion function.

// Disable file completion for a specific flag
cmd.RegisterFlagCompletionFunc("flag-name", cobra.NoFileCompletions)

// Recursively set default for a command tree
cmd.CompletionOptions.SetDefaultShellCompDirective(ShellCompDirectiveNoFileComp)

// Re-enable file completion for a specific flag in a NoFileComp tree
cmd.RegisterFlagCompletionFunc("flag-name", cobra.FixedCompletions(nil, ShellCompDirectiveDefault))

If you need to provide your own completion command (e.g., for backwards compatibility or custom behavior), you can implement it manually. If using cobra-cli, run cobra-cli add completion and then implement the Run function using Cobra's generation methods:

• cmd.Root().GenBashCompletion(os.Stdout)
• cmd.Root().GenZshCompletion(os.Stdout)
• cmd.Root().GenFishCompletion(os.Stdout, true)
• cmd.Root().GenPowerShellCompletionWithDesc(os.Stdout)

Warning: Ensure your command does not print anything to stdout other than the completion script itself (e.g., from config file loading), as this will break the shell completion logic.

var completionCmd = &cobra.Command{
	Use:   "completion [bash|zsh|fish|powershell]",
	Short: "Generate completion script",
	ValidArgs:             []string{"bash", "zsh", "fish", "powershell"},
	Args:                  cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs),
	Run: func(cmd *cobra.Command, args []string) {
		switch args[0] {
		case "bash":
			cmd.Root().GenBashCompletion(os.Stdout)
		case "zsh":
			cmd.Root().GenZshCompletion(os.Stdout)
		case "fish":
			cmd.Root().GenFishCompletion(os.Stdout, true)
		case "powershell":
			cmd.Root().GenPowerShellCompletionWithDesc(os.Stdout)
		}
	},
}