Cobra

https://github.com/spf13/cobra
Admin
Cobra is a library for creating powerful modern CLI applications, offering features like...
Tokens:33,520
Snippets:276
Trust Score:9.9
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Cobra library with go get

Source: https://github.com/spf13/cobra/blob/main/README.md

Use this command to install the latest version of the Cobra library. Run this before importing Cobra in your Go application.

```bash
go get -u github.com/spf13/cobra@latest
```

--------------------------------

### Generate Markdown docs for the entire command tree (kubectl example)

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/md.md

This example generates Markdown docs for the kubectl command from the Kubernetes project. It creates a kubectl command and calls doc.GenMarkdownTree to generate a series of files, one for each command in the tree, in the current directory.

```go
package main

import (
	"log"
	"io"
	"os"

	"k8s.io/kubernetes/pkg/kubectl/cmd"
	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"

	"github.com/spf13/cobra/doc"
)

func main() {
	kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, io.Discard, io.Discard)
	err := doc.GenMarkdownTree(kubectl, "./")
	if err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### fish completion descriptions example

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows the output of pressing Tab after 'helm s' in fish, displaying commands with descriptions in parentheses.

```shell
$ helm s[tab]
search  (search for a keyword in charts)  show  (show information of a chart)  status  (displays the status of the named release)

```

--------------------------------

### Example output of dynamic flag completion

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows the tab-completion output for the dynamic completion example.

```bash
$ helm status --output [tab][tab]
json table yaml
```

--------------------------------

### Full root.go with flags and configuration

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Complete root command setup including persistent flags, Viper configuration, and initConfig function. Uses cobra.OnInitialize and binds flags to Viper.

```go
package cmd

import (
	"fmt"
	"os"

	"github.com/spf13/cobra"
	"github.com/spf13/viper"
)

var (
	// Used for flags.
	cfgFile     string
	userLicense string

	rootCmd = &cobra.Command{
		Use:   "cobra-cli",
		Short: "A generator for Cobra based Applications",
		Long: `Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.`,
	}
)

// Execute executes the root command.
func Execute() error {
	return rootCmd.Execute()
}

func init() {
	cobra.OnInitialize(initConfig)

	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.cobra.yaml)")
	rootCmd.PersistentFlags().StringP("author", "a", "YOUR NAME", "author name for copyright attribution")
	rootCmd.PersistentFlags().StringVarP(&userLicense, "license", "l", "", "name of license for the project")
	rootCmd.PersistentFlags().Bool("viper", true, "use Viper for configuration")
	viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
	viper.BindPFlag("useViper", rootCmd.PersistentFlags().Lookup("viper"))
	viper.SetDefault("author", "NAME HERE <EMAIL ADDRESS>")
	viper.SetDefault("license", "apache")

	rootCmd.AddCommand(addCmd)
	rootCmd.AddCommand(initCmd)
}

func initConfig() {
	if cfgFile != "" {
		// Use config file from the flag.
		viper.SetConfigFile(cfgFile)
	} else {
		// Find home directory.
		home, err := os.UserHomeDir()
		cobra.CheckErr(err)

		// Search config in home directory with name ".cobra" (without extension).
		viper.AddConfigPath(home)
		viper.SetConfigType("yaml")
		viper.SetConfigName(".cobra")
	}

	viper.AutomaticEnv()

	if err := viper.ReadInConfig(); err == nil {
		fmt.Println("Using config file:", viper.ConfigFileUsed())
	}
}
```

--------------------------------

### Example output of kubectl get completion

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows the tab completion results for the kubectl get command when ValidArgs is set.

```bash
$ kubectl get [tab][tab]
node   pod   replicationcontroller   service
```

--------------------------------

### zsh completion descriptions example

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows the output of pressing Tab after 'helm s' in zsh, displaying commands with descriptions.

```shell
$ helm s[tab]
search  -- search for a keyword in charts
show    -- show information of a chart
status  -- displays the status of the named release

```

--------------------------------

### Fish completions with descriptions

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Example of fish completions with descriptions, showing the output when pressing tab after 'helm s'. Descriptions are provided automatically based on usage information.

```shell
# With descriptions
$ helm s[tab]
search  (search for a keyword in charts)  show  (show information of a chart)  status  (displays the status of the named release)
```

--------------------------------

### Install cobra-cli generator

Source: https://github.com/spf13/cobra/blob/main/README.md

Use this command to install the cobra-cli command line program. It bootstraps application scaffolding for Cobra-based applications.

```bash
go install github.com/spf13/cobra-cli@latest
```

--------------------------------

### Customize ReST tree generation with filePrepender and linkHandler

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/rest.md

This example shows the signature of `GenReSTTreeCustom`, an alternate version of `GenReSTTree` that accepts a `filePrepender` and a `linkHandler` callback. The `filePrepender` can prepend front matter to the output file, and the `linkHandler` can customize command links.

```go
func GenReSTTreeCustom(cmd *Command, dir string, filePrepender func(string) string, linkHandler func(string, string) string) error {
	//...
}
```

--------------------------------

### Behavior of Active Help for helm repo add

Source: https://github.com/spf13/cobra/blob/main/site/content/active_help.md

Console output showing the Active Help messages produced by the previous Go example for the 'helm repo add' command at different argument stages.

```console
$ helm repo add [tab]
You must choose a name for the repo you are adding

$ helm repo add grafana [tab]
You must specify the URL for the repo you are adding

$ helm repo add grafana https://grafana.github.io/helm-charts [tab]
This command does not take any more arguments
```

--------------------------------

### Customize single command generation with linkHandler

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/rest.md

This example shows the signature of `GenReSTCustom`, an alternate version of `GenReST` that accepts a `linkHandler` callback. It allows customization of rendered links for the single command's documentation.

```go
func GenReSTCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string, string) string) error {
	//...
}
```

--------------------------------

### Cobra PreRun and PostRun Hooks Example

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Complete Go program showing root and sub commands with PersistentPreRun, PreRun, Run, PostRun, and PersistentPostRun hooks. Demonstrates that only the first persistent hook in the chain executes for child commands unless EnableTraverseRunHooks is set.

```go
package main

import (
  "fmt"

  "github.com/spf13/cobra"
)

func main() {

  var rootCmd = &cobra.Command{
    Use:   "root [sub]",
    Short: "My root command",
    PersistentPreRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside rootCmd PersistentPreRun with args: %v\n", args)
    },
    PreRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside rootCmd PreRun with args: %v\n", args)
    },
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside rootCmd Run with args: %v\n", args)
    },
    PostRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside rootCmd PostRun with args: %v\n", args)
    },
    PersistentPostRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside rootCmd PersistentPostRun with args: %v\n", args)
    },
  }

  var subCmd = &cobra.Command{
    Use:   "sub [no options!]",
    Short: "My subcommand",
    PreRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside subCmd PreRun with args: %v\n", args)
    },
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside subCmd Run with args: %v\n", args)
    },
    PostRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside subCmd PostRun with args: %v\n", args)
    },
    PersistentPostRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside subCmd PersistentPostRun with args: %v\n", args)
    },
  }

  rootCmd.AddCommand(subCmd)

  rootCmd.SetArgs([]string{""})
  rootCmd.Execute()
  fmt.Println()
  rootCmd.SetArgs([]string{"sub", "arg1", "arg2"})
  rootCmd.Execute()
}
```

```text
Inside rootCmd PersistentPreRun with args: []
Inside rootCmd PreRun with args: []
Inside rootCmd Run with args: []
Inside rootCmd PostRun with args: []
Inside rootCmd PersistentPostRun with args: []

Inside rootCmd PersistentPreRun with args: [arg1 arg2]
Inside subCmd PreRun with args: [arg1 arg2]
Inside subCmd Run with args: [arg1 arg2]
Inside subCmd PostRun with args: [arg1 arg2]
Inside subCmd PersistentPostRun with args: [arg1 arg2]
```

--------------------------------

### Active Help for nouns using ValidArgsFunction

Source: https://github.com/spf13/cobra/blob/main/site/content/active_help.md

Go example showing how to add Active Help messages for a noun completion using cobra.AppendActiveHelp(...) inside ValidArgsFunction. The messages guide the user through required arguments for the 'add' command.

```go
cmd := &cobra.Command{
	Use:   "add [NAME] [URL]",
	Short: "add a chart repository",
	Args:  require.ExactArgs(2),
	RunE: func(cmd *cobra.Command, args []string) error {
		return addRepo(args)
	},
	ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
		var comps []cobra.Completion
		if len(args) == 0 {
			comps = cobra.AppendActiveHelp(comps, "You must choose a name for the repo you are adding")
		} else if len(args) == 1 {
			comps = cobra.AppendActiveHelp(comps, "You must specify the URL for the repo you are adding")
		} else {
			comps = cobra.AppendActiveHelp(comps, "This command does not take any more arguments")
		}
		return comps, cobra.ShellCompDirectiveNoFileComp
	},
}
```

--------------------------------

### Active Help example with helm repo add

Source: https://github.com/spf13/cobra/blob/main/site/content/active_help.md

Shows how Active Help messages appear during shell completion for the 'helm repo add' command. The first tab shows a hint, the second tab shows a hint for the package command, and the third tab shows normal file completions.

```console
$ helm repo add [tab]
You must choose a name for the repo you are adding.

$ bin/helm package [tab]
Please specify the path to the chart to package

$ bin/helm package [tab][tab]
bin/    internal/    scripts/    pkg/     testdata/
```

--------------------------------

### Behavior of Active Help for --version flag

Source: https://github.com/spf13/cobra/blob/main/site/content/active_help.md

Console output showing the Active Help message and the normal completions for the --version flag of the 'helm install' command.

```console
$ bin/helm install myrelease --version 2.0.[tab]
You must first specify the chart to install before the --version flag can be completed

$ bin/helm install myrelease bitnami/solr --version 2.0.[tab][tab]
2.0.1  2.0.2  2.0.3
```

--------------------------------

### Example output of required flag completions

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows the expected tab-completion output when flags are marked required.

```bash
$ kubectl exec [tab][tab]
-c            --container=  -p            --pod=
```

--------------------------------

### Generate ReST docs for a single command using GenReST

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/rest.md

This example shows how to use `doc.GenReST` to generate ReST documentation for a single command into a `bytes.Buffer`. It is useful when you want more control over the output or only need docs for one command rather than the entire command tree.

```go
	out := new(bytes.Buffer)
	err := doc.GenReST(cmd, out)
	if err != nil {
		log.Fatal(err)
	}

```

--------------------------------

### Generate Markdown docs for a single command using doc.GenMarkdownTree

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/md.md

This example creates a simple cobra command and generates a Markdown file in /tmp using doc.GenMarkdownTree. The output file will be /tmp/test.md.

```go
package main

import (
	"log"

	"github.com/spf13/cobra"
	"github.com/spf13/cobra/doc"
)

func main() {
	cmd := &cobra.Command{
		Use:   "test",
		Short: "my test program",
	}
	err := doc.GenMarkdownTree(cmd, "/tmp")
	if err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Generate ReST tree for a command tree

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/rest.md

This example generates ReST documentation for the entire kubectl command tree in the Kubernetes project. It uses `doc.GenReSTTree` with the `kubectl` command and writes output files to the current directory.

```go
package main

import (
	"log"
	"io"
	"os"

	"k8s.io/kubernetes/pkg/kubectl/cmd"
	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"

	"github.com/spf13/cobra/doc"
)

func main() {
	kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, io.Discard, io.Discard)
	err := doc.GenReSTTree(kubectl, "./")
	if err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Example of unknown command suggestion for kubectl

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Shows the console output when a user types a command that is not close in string distance but is explicitly suggested via the SuggestFor attribute.

```console
$ kubectl remove
Error: unknown command "remove" for "kubectl"

Did you mean this?
        delete

Run 'kubectl help' for usage.

```

--------------------------------

### Customize output with linkHandler for internal links

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/md.md

This example shows how to customize the rendered internal links to commands using the linkHandler callback. It converts a filename to a lowercased URL path under /commands/.

```go
linkHandler := func(name string) string {
	base := strings.TrimSuffix(name, path.Ext(name))
	return "/commands/" + strings.ToLower(base) + "/"
}
```

--------------------------------

### Example shell completion output for helm status

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows the expected output when pressing tab after 'helm status' with releases harbor, notary, rook, and thanos.

```bash
$ helm status [tab][tab]
harbor notary rook thanos
```

--------------------------------

### Generate ReST tree for a simple command

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/rest.md

This example uses `doc.GenReSTTree` to generate a ReST document for a single command in the `/tmp` directory. It creates a `cobra.Command` named 'test' and passes it to `GenReSTTree`, which outputs a file named `/tmp/test.rst`.

```go
package main

import (
	"log"

	"github.com/spf13/cobra"
	"github.com/spf13/cobra/doc"
)

func main() {
	cmd := &cobra.Command{
		Use:   "test",
		Short: "my test program",
	}
	err := doc.GenReSTTree(cmd, "/tmp")
	if err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### ValidArgs with CompletionWithDesc

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Example of using cobra.CompletionWithDesc in ValidArgs to provide completions with descriptions.

```go
ValidArgs: []cobra.Completion{
	cobra.CompletionWithDesc("bash", "Completions for bash"),
	cobra.CompletionWithDesc("zsh", "Completions for zsh")
	}

```

--------------------------------

### Bash completion V2 with and without descriptions

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows the output of bash completion V2 with and without descriptions. With descriptions, each command is followed by its usage in parentheses. Without descriptions, only the command names are listed. This example uses the helm command.

```text
# With descriptions
$ helm s[tab][tab]
search  (search for a keyword in charts)           status  (display the status of the named release)
show    (show information of a chart)

# Without descriptions
$ helm s[tab][tab]
search  show  status
```

--------------------------------

### Fish completions without descriptions

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Example of fish completions without descriptions, showing the output when pressing tab after 'helm s'. Descriptions are omitted.

```shell
# Without descriptions
$ helm s[tab]
search  show  status
```

--------------------------------

### Create a kubectl plugin with cobra.CommandDisplayNameAnnotation

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Use this Go code to define a root command with the display name annotation so help and completions show 'kubectl myplugin' instead of 'kubectl-myplugin'. The example defines a root command and a subcommand, then executes the root command.

```go
package main

import (
	"fmt"

	"github.com/spf13/cobra"
)

func main() {
	rootCmd := &cobra.Command{
		Use: "kubectl-myplugin",
		Annotations: map[string]string{
			cobra.CommandDisplayNameAnnotation: "kubectl myplugin",
		},
	}
	subCmd := &cobra.Command{
		Use: "subcmd",
		Run: func(cmd *cobra.Command, args []string) {
			fmt.Println("kubectl myplugin subcmd")
		},
	}
	rootCmd.AddCommand(subCmd)
	rootCmd.Execute()
}
```

--------------------------------

### Zsh completion examples with and without descriptions

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows the output of zsh completions with descriptions (using the default generation) and without descriptions (using GenZshCompletionNoDesc or GenZshCompletionFileNoDesc). The first block shows the completion with descriptions, the second without.

```shell
# With descriptions
$ helm s[tab]
search  -- search for a keyword in charts
show    -- show information of a chart
status  -- displays the status of the named release

```

```shell
# Without descriptions
$ helm s[tab]
search  show  status

```

--------------------------------

### Import Cobra in Go application

Source: https://github.com/spf13/cobra/blob/main/README.md

Add this import statement to your Go source file to use Cobra. It must be placed after installing the library.

```go
import "github.com/spf13/cobra"
```

--------------------------------

### Active Help for flags using RegisterFlagCompletionFunc

Source: https://github.com/spf13/cobra/blob/main/site/content/active_help.md

Go example showing how to add Active Help for a flag completion using cobra.AppendActiveHelp(...) inside a flag completion function. It prints a message when the user has not provided enough arguments to complete the --version flag.

```go
_ = cmd.RegisterFlagCompletionFunc("version", func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
		if len(args) != 2 {
			return cobra.AppendActiveHelp(nil, "You must first specify the chart to install before the --version flag can be completed"), cobra.ShellCompDirectiveNoFileComp
		}
		return compVersionFlag(args[1], toComplete)
	})
```

--------------------------------

### Template for front matter with filePrepender

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/rest.md

This example shows a typical `filePrepender` implementation for adding front matter to the generated ReST file, suitable for use with Hugo. It formats a date, title, slug, and URL based on the output file path.

```go
const fmTemplate = `---
date: %s
title: "%s"
slug: %s
url: %s
---
`
filePrepender := func(filename string) string {
	now := time.Now().Format(time.RFC3339)
	name := filepath.Base(filename)
	base := strings.TrimSuffix(name, path.Ext(name))
	url := "/commands/" + strings.ToLower(base) + "/"
	return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url)
}
```

--------------------------------

### ValidArgsFunction with CompletionWithDesc

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Example of using cobra.CompletionWithDesc in a ValidArgsFunction to provide completions with descriptions.

```go
ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
	return []cobra.Completion{
		cobra.CompletionWithDesc("harbor", "An image registry"),
		cobra.CompletionWithDesc("thanos", "Long-term metrics")
		}, cobra.ShellCompDirectiveNoFileComp
}}

```

--------------------------------

### Go example: Using RunE to return an error

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Defines a Cobra command 'try' that uses RunE to return an error from someFunc, which can then be caught at the execute function call.

```go
package cmd

import (
  "fmt"

  "github.com/spf13/cobra"
)

func init() {
  rootCmd.AddCommand(tryCmd)
}

var tryCmd = &cobra.Command{
  Use:   "try",
  Short: "Try and possibly fail at something",
  RunE: func(cmd *cobra.Command, args []string) error {
    if err := someFunc(); err != nil {
	return err
    }
    return nil
  },
}
```

--------------------------------

### Sphinx cross-referencing linkHandler

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/rest.md

This example shows a `linkHandler` function that generates Sphinx cross-referencing format for links. It formats a command name and reference as `:ref:`name <ref>``, useful when converting ReST to HTML or using Sphinx.

```go
// Sphinx cross-referencing format
linkHandler := func(name, ref string) string {
    return fmt.Sprintf(":ref:`%s <%s>`", name, ref)
}
```

--------------------------------

### Cobra example: defining commands and subcommands

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

This Go program defines a root command 'app' with two subcommands 'print' and 'echo', and a child command 'times' under 'echo'. It uses cobra.MinimumNArgs(1) to require at least one argument, and adds a flag '--times' to the 'times' command. The root command has no Run function, so a subcommand is required. Execute the program to see the commands in action.

```go
package main

import (
  "fmt"
  "strings"

  "github.com/spf13/cobra"
)

func main() {
  var echoTimes int

  var cmdPrint = &cobra.Command{
    Use:   "print [string to print]",
    Short: "Print anything to the screen",
    Long: `print is for printing anything back to the screen.
For many years people have printed back to the screen.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Println("Print: " + strings.Join(args, " "))
    },
  }

  var cmdEcho = &cobra.Command{
    Use:   "echo [string to echo]",
    Short: "Echo anything to the screen",
    Long: `echo is for echoing anything back.
Echo works a lot like print, except it has a child command.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Println("Echo: " + strings.Join(args, " "))
    },
  }

  var cmdTimes = &cobra.Command{
    Use:   "times [string to echo]",
    Short: "Echo anything to the screen more times",
    Long: `echo things multiple times back to the user by providing
a count and a string.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      for i := 0; i < echoTimes; i++ {
        fmt.Println("Echo: " + strings.Join(args, " "))
      }
    },
  }

  cmdTimes.Flags().IntVarP(&echoTimes, "times", "t", 1, "times to echo the input")

  var rootCmd = &cobra.Command{Use: "app"}
  rootCmd.AddCommand(cmdPrint, cmdEcho)
  cmdEcho.AddCommand(cmdTimes)
  rootCmd.Execute()
}
```

--------------------------------

### Example of unknown command suggestion for hugo

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Shows the console output when a user types a misspelled command. Cobra suggests the closest matching subcommand based on Levenshtein distance.

```console
$ hugo srever
Error: unknown command "srever" for "hugo"

Did you mean this?
        server

Run 'hugo --help' for usage.

```

--------------------------------

### Read Active Help config and conditionally append help messages in ValidArgsFunction

Source: https://github.com/spf13/cobra/blob/main/site/content/active_help.md

Use cobra.GetActiveHelpConfig(cmd) to read the Active Help configuration and cobra.AppendActiveHelp to add messages based on the level. The example checks for 'off' and 'local' levels to decide which messages to show.

```go
ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
	activeHelpLevel := cobra.GetActiveHelpConfig(cmd)

	var comps []cobra.Completion
	if len(args) == 0 {
		if activeHelpLevel != "off"  {
			comps = cobra.AppendActiveHelp(comps, "You must choose a name for the repo you are adding")
		}
	} else if len(args) == 1 {
		if activeHelpLevel != "off" {
			comps = cobra.AppendActiveHelp(comps, "You must specify the URL for the repo you are adding")
		}
	} else {
		if activeHelpLevel == "local" {
			comps = cobra.AppendActiveHelp(comps, "This command does not take any more arguments")
		}
	}
	return comps, cobra.ShellCompDirectiveNoFileComp
},
```

--------------------------------

### Array/Slice Flag with StringArrayVarP and StringSliceVarP

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Use StringArrayVarP to collect multiple values from repeated flag usage (e.g., --input file1 --input file2) or StringSliceVarP for comma-separated values. The example shows both alternatives, with the StringSliceVarP line commented out.

```go
var inputFiles []string

func init() {
  // StringArrayVarP allows multiple values: --input file1.txt --input file2.txt
  rootCmd.Flags().StringArrayVarP(&inputFiles, "input", "i", []string{}, "input files (can be repeated)")

  // Alternative: StringSliceVarP for comma-separated values
  // rootCmd.Flags().StringSliceVarP(&inputFiles, "input", "i", []string{}, "input files (comma-separated or repeated)")
}
```

--------------------------------

### Minimal main.go for Cobra application

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Bare main.go that initializes Cobra by calling cmd.Execute(). The import path is a placeholder to be replaced with the actual path to the cmd package.

```go
package main

import "{pathToYourApp}/cmd"

func main() {
  cmd.Execute()
}
```

--------------------------------

### Run the plugin as kubectl myplugin

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Console output showing the help text when the plugin is run as 'kubectl myplugin'. It lists available commands and flags, demonstrating the effect of the display name annotation.

```console
$ kubectl myplugin
Usage:
  kubectl myplugin [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  subcmd

Flags:
  -h, --help   help for kubectl myplugin

Use "kubectl myplugin [command] --help" for more information about a command.
```

--------------------------------

### Configure bash aliases for completions

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows how to set up a bash alias so that completions work for the alias. The alias command and the complete command must be run together. After running these, typing the alias followed by a tab will show available commands.

```bash
alias aliasname=origcommand
complete -o default -F __start_origcommand aliasname

# and now when you run `aliasname` completion will make
# suggestions as it did for `origcommand`.

$ aliasname <tab><tab>
completion     firstcommand   secondcommand
```

--------------------------------

### PowerShell alias completion setup

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Configures a PowerShell alias for a Cobra command and registers an argument completer for the alias. The completer block variable is named `$__<programName>CompleterBlock` with `-` and `:` replaced by `_`.

```powershell
$ sal aliasname origcommand
$ Register-ArgumentCompleter -CommandName 'aliasname' -ScriptBlock $__origcommandCompleterBlock

# and now when you run `aliasname` completion will make
# suggestions as it did for `origcommand`.

$ aliasname <tab>
completion     firstcommand   secondcommand
```

--------------------------------

### Create rootCmd in root.go

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Defines a root command with Use, Short, Long, and Run fields. The Execute function runs the root command and exits on error.

```go
var rootCmd = &cobra.Command{
  Use:   "hugo",
  Short: "Hugo is a very fast static site generator",
  Long: `A Fast and Flexible Static Site Generator built with
                love by spf13 and friends in Go.
                Complete documentation is available at https://gohugo.io/documentation/`,
  Run: func(cmd *cobra.Command, args []string) {
    // Do Stuff Here
  },
}

func Execute() {
  if err := rootCmd.Execute(); err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
  }
}
```

--------------------------------

### Generate YAML docs for a cobra command with doc.GenYamlTree

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/yaml.md

Creates a simple cobra command and generates a YAML document at /tmp/test.yaml using doc.GenYamlTree. The command has Use: "test" and Short: "my test program".

```go
package main

import (
	"log"

	"github.com/spf13/cobra"
	"github.com/spf13/cobra/doc"
)

func main() {
	cmd := &cobra.Command{
		Use:   "test",
		Short: "my test program",
	}
	err := doc.GenYamlTree(cmd, "/tmp")
	if err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Debug flag completion with __complete

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Shows how to debug flag completion by running the __complete command. The output includes the completion choices and the directive on stderr.

```bash
$ helm __complete status --output ""
json
table
yaml
:4
Completion ended with directive: ShellCompDirectiveNoFileComp # This is on stderr
```

--------------------------------

### Generate YAML docs for a single command with doc.GenYaml

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/yaml.md

Writes the YAML doc for only the given command into a bytes.Buffer using doc.GenYaml. This provides more control than GenYamlTree when you only need one command.

```go
out := new(bytes.Buffer)
doc.GenYaml(cmd, out)
```

--------------------------------

### Disable --no-descriptions flag

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Set this on the root command to prevent the completion sub-commands from providing the --no-descriptions flag.

```go
rootCmd.CompletionOptions.DisableNoDescFlag = true
```

--------------------------------

### Create version command in version.go

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Defines a version command that prints the Hugo version. Added to the root command in init().

```go
package cmd

import (
  "fmt"

  "github.com/spf13/cobra"
)

func init() {
  rootCmd.AddCommand(versionCmd)
}

var versionCmd = &cobra.Command{
  Use:   "version",
  Short: "Print the version number of Hugo",
  Long:  `All software has versions. This is Hugo's`,
  Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Hugo Static Site Generator v0.9 -- HEAD")
  },
}
```

--------------------------------

### Cobra help customization functions

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Functions to customize the help command, help function, and help template. SetHelpTemplate uses text/template and can increase compiled executable size.

```go
cmd.SetHelpCommand(cmd *Command)
cmd.SetHelpFunc(f func(*Command, []string))
cmd.SetHelpTemplate(s string)
```

--------------------------------

### Customize output with GenMarkdownTreeCustom and GenMarkdownCustom

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/md.md

These are the signatures for the custom versions of GenMarkdownTree and GenMarkdown. They accept callbacks for file prepending and link handling to customize the generated Markdown output.

```go
func GenMarkdownTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error {
	//...
}
```

```go
func GenMarkdownCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
	//...
}
```

--------------------------------

### Generate Markdown docs for a single command using doc.GenMarkdown

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/md.md

This snippet shows how to generate Markdown docs for a single command using doc.GenMarkdown, writing the output to a bytes.Buffer. It is useful when you need more control over the output or only want docs for one command.

```go
out := new(bytes.Buffer)
err := doc.GenMarkdown(cmd, out)
if err != nil {
	log.Fatal(err)
}
```

--------------------------------

### Implement __kubectl_get_namespaces bash function

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/bash.md

Implements the __kubectl_get_namespaces function that is referenced by the flag annotation. It uses a Go template to list namespaces and sets COMPREPLY with the output.

```bash
__kubectl_get_namespaces()
{
    local template
    template="{{ range .items  }}{{ .metadata.name }} {{ end }}"
    local kubectl_out
    if kubectl_out=$(kubectl get -o template --template="${template}" namespace 2>/dev/null); then
        COMPREPLY=( $( compgen -W "${kubectl_out}[*]" -- "$cur" ) )
    fi
}
```

--------------------------------

### Cobra project directory structure

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Shows the typical folder layout for a Cobra application, with a cmd/ directory for commands and a main.go at the root.

```console
▾ appName/
  ▾ cmd/
      add.go
      your.go
      commands.go
      here.go
  main.go
```

--------------------------------

### doc.GenYamlTreeCustom

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/yaml.md

Generates YAML documentation for a command tree with custom file prepending and link handling.

```APIDOC
## [FUNCTION] doc.GenYamlTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error

### Description
Generates YAML documentation for a cobra command tree with custom callbacks to control file prepending and link handling.

### Function Signature
```go
func GenYamlTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error
```

### Parameters
- **cmd** (*Command) - Required - The root cobra command.
- **dir** (string) - Required - The directory where the YAML files will be written.
- **filePrepender** (func(string) string) - Required - A callback that receives the full filepath and returns a string to prepend to the rendered YAML file (e.g., front matter).
- **linkHandler** (func(string) string) - Required - A callback that receives a filename and returns a custom link string for internal links.

### Return Value
- **error** - Returns an error if the generation fails.

### Example
```go
const fmTemplate = `---
date: %s
title: "%s"
slug: %s
url: %s
---
`

filePrepender := func(filename string) string {
	now := time.Now().Format(time.RFC3339)
	name := filepath.Base(filename)
	base := strings.TrimSuffix(name, path.Ext(name))
	url := "/commands/" + strings.ToLower(base) + "/"
	return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url)
}

linkHandler := func(name string) string {
	base := strings.TrimSuffix(name, path.Ext(name))
	return "/commands/" + strings.ToLower(base) + "/"
}
```
```

--------------------------------

### Generate YAML docs for the entire kubectl command tree

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/yaml.md

Generates YAML docs for the kubectl command from the Kubernetes project, writing one file per command in the tree to the current directory. Uses doc.GenYamlTree with the kubectl command.

```go
package main

import (
	"io"
	"log"
	"os"

	"k8s.io/kubernetes/pkg/kubectl/cmd"
	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"

	"github.com/spf13/cobra/doc"
)

func main() {
	kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, io.Discard, io.Discard)
	err := doc.GenYamlTree(kubectl, "./")
	if err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### doc.GenYamlCustom

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/yaml.md

Generates YAML documentation for a single cobra command with a custom link handler.

```APIDOC
## [FUNCTION] doc.GenYamlCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error

### Description
Generates YAML documentation for a single cobra command with a custom link handler.

### Function Signature
```go
func GenYamlCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error
```

### Parameters
- **cmd** (*Command) - Required - The cobra command.
- **out** (*bytes.Buffer) - Required - The buffer to which the YAML output is written.
- **linkHandler** (func(string) string) - Required - A callback that receives a filename and returns a custom link string for internal links.

### Return Value
- **error** - Returns an error if the generation fails.

### Example
```go
// linkHandler example
linkHandler := func(name string) string {
	base := strings.TrimSuffix(name, path.Ext(name))
	return "/commands/" + strings.ToLower(base) + "/"
}
```
```

--------------------------------

### Generate man page with doc.GenManTree

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/man.md

Use this Go program to generate a man page for a cobra command. It creates a command with Use and Short fields, sets a GenManHeader with Title and Section, and calls doc.GenManTree to write the man page to /tmp. The output file is /tmp/test.3.

```go
package main

import (
	"log"

	"github.com/spf13/cobra"
	"github.com/spf13/cobra/doc"
)

func main() {
	cmd := &cobra.Command{
		Use:   "test",
		Short: "my test program",
	}
	header := &doc.GenManHeader{
		Title: "MINE",
		Section: "3",
	}
	err := doc.GenManTree(cmd, header, "/tmp")
	if err != nil {
		log.Fatal(err)
	}
}
```

--------------------------------

### Custom completion command in Go

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

A custom completion command that writes shell scripts to stdout, supporting bash, zsh, fish, and powershell. It includes usage instructions in the long description and uses GenBashCompletion, GenZshCompletion, GenFishCompletion, and GenPowerShellCompletionWithDesc.

```go
var completionCmd = &cobra.Command{
	Use:   "completion [bash|zsh|fish|powershell]",
	Short: "Generate completion script",
	Long: fmt.Sprintf(`To load completions:

Bash:

  $ source <(%[1]s completion bash)

  # To load completions for each session, execute once:
  # Linux:
  $ %[1]s completion bash > /etc/bash_completion.d/%[1]s
  # macOS:
  $ %[1]s completion bash > $(brew --prefix)/etc/bash_completion.d/%[1]s

Zsh:

  # If shell completion is not already enabled in your environment,
  # you will need to enable it.  You can execute the following once:

  $ echo "autoload -U compinit; compinit" >> ~/.zshrc

  # To load completions for each session, execute once:
  $ %[1]s completion zsh > "${fpath[1]}/_%[1]s"

  # You will need to start a new shell for this setup to take effect.

fish:

  $ %[1]s completion fish | source

  # To load completions for each session, execute once:
  $ %[1]s completion fish > ~/.config/fish/completions/%[1]s.fish

PowerShell:

  PS> %[1]s completion powershell | Out-String | Invoke-Expression

  # To load completions for every new session, run:
  PS> %[1]s completion powershell > %[1]s.ps1
  # and source this file from your PowerShell profile.
`,cmd.Root().Name()),
	DisableFlagsInUseLine: true,
	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)
		}
	},
}
```

--------------------------------

### Customize YAML tree generation with GenYamlTreeCustom

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/yaml.md

Shows the signature of GenYamlTreeCustom, which accepts a filePrepender and linkHandler callback to customize the generated YAML files. The filePrepender can prepend front matter, and linkHandler customizes internal links.

```go
func GenYamlTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error {
	//...
}
```

--------------------------------

### Directory structure for organizing subcommands

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Shows the recommended directory layout for a Cobra application with nested subcommands, where each subcommand is defined in its own package and added via AddCommand in init functions.

```console
├── cmd
│   ├── root.go
│   └── sub1
│       ├── sub1.go
│       └── sub2
│           ├── leafA.go
│           ├── leafB.go
│           └── sub2.go
└── main.go
```

--------------------------------

### Cobra help command output

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

Automatically generated help output when running 'cobra-cli help'. Shows usage, available commands, and flags. No additional configuration needed.

```console
$ cobra-cli help

Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.

Usage:
  cobra-cli [command]

Available Commands:
  add         Add a command to a Cobra Application
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  init        Initialize a Cobra Application

Flags:
  -a, --author string    author name for copyright attribution (default "YOUR NAME")
      --config string    config file (default is $HOME/.cobra.yaml)
  -h, --help             help for cobra-cli
  -l, --license string   name of license for the project
      --viper            use Viper for configuration

Use "cobra-cli [command] --help" for more information about a command.
```

--------------------------------

### doc.GenYaml

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/yaml.md

Generates YAML documentation for a single cobra command.

```APIDOC
## [FUNCTION] doc.GenYaml(cmd *Command, out *bytes.Buffer) error

### Description
Generates YAML documentation for a single cobra command and writes it to the provided buffer.

### Function Signature
```go
func GenYaml(cmd *Command, out *bytes.Buffer) error
```

### Parameters
- **cmd** (*Command) - Required - The cobra command for which to generate documentation.
- **out** (*bytes.Buffer) - Required - The buffer to which the YAML output is written.

### Return Value
- **error** - Returns an error if the generation fails.

### Example
```go
out := new(bytes.Buffer)
doc.GenYaml(cmd, out)
```

### Notes
- Generates documentation for only the specified command, not its subcommands.
```

--------------------------------

### Using the Verbose Counter in Command Logic

Source: https://github.com/spf13/cobra/blob/main/site/content/user_guide.md

In the command's Run function, switch on the 'verbose' counter to set logging levels: 0 (default), 1 (info), 2 (debug), 3 (trace). The default case handles values above 3 by setting trace level.

```go
Run: func(cmd *cobra.Command, args []string) {
  switch verbose {
  case 0:
    // Default: no verbose output
  case 1:
    // Info level logging
    log.SetLevel(log.InfoLevel)
  case 2:
    // Debug level logging
    log.SetLevel(log.DebugLevel)
  case 3:
    // Trace level logging
    log.SetLevel(log.TraceLevel)
  default:
    // Maximum verbosity
    log.SetLevel(log.TraceLevel)
  }
},
```

--------------------------------

### Disable descriptions for completions

Source: https://github.com/spf13/cobra/blob/main/site/content/completions/_index.md

Set this on the root command to completely disable descriptions for completions.

```go
rootCmd.CompletionOptions.DisableDescriptions = true
```

--------------------------------

### Customize YAML generation for a single command with GenYamlCustom

Source: https://github.com/spf13/cobra/blob/main/site/content/docgen/yaml.md

Shows the signature of GenYamlCustom, which accepts a linkHandler callback to customize internal links in the generated YAML for a single command.

```go
func GenYamlCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error {
	//...
}
```
Tokens:
Raw