cobra Documentation

File: README.md Copy Chapter

Cobra is a library for creating powerful modern CLI applications.

Visit Cobra.dev for extensive documentation

Cobra is used in many Go projects such as Kubernetes,
Hugo, and GitHub CLI to
name a few. This list contains a more extensive list of projects using Cobra.

Overview

Cobra is a library providing a simple interface to create powerful modern CLI
interfaces similar to git & go tools.

Cobra provides:

• Easy subcommand-based CLIs: app server, app fetch, etc.
• Fully POSIX-compliant flags (including short & long versions)
• Nested subcommands
• Global, local and cascading flags
• Intelligent suggestions (app srver... did you mean app server?)
• Automatic help generation for commands and flags
• Grouping help for subcommands
• Automatic help flag recognition of -h, --help, etc.
• Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell)
• Automatically generated man pages for your application
• Command aliases so you can change things without breaking them
• The flexibility to define your own help, usage, etc.
• Optional seamless integration with viper for 12-factor apps

Concepts

Cobra is built on a structure of commands, arguments & flags.

Commands represent actions, Args are things and Flags are modifiers for those actions.

The best applications read like sentences when used, and as a result, users
intuitively know how to interact with them.

The pattern to follow is
APPNAME VERB NOUN --ADJECTIVE
or
APPNAME COMMAND ARG --FLAG.

A few good real world examples may better illustrate this point.

In the following example, 'server' is a command, and 'port' is a flag:

hugo server --port=1313

In this command we are telling Git to clone the url bare.

git clone URL --bare

Commands Copy Chapter

Command is the central point of the application. Each interaction that
the application supports will be contained in a Command. A command can
have children commands and optionally run an action.

In the example above, 'server' is the command.

More about cobra.Command

Flags Copy Chapter

A flag is a way to modify the behavior of a command. Cobra supports
fully POSIX-compliant flags as well as the Go flag package.
A Cobra command can define flags that persist through to children commands
and flags that are only available to that command.

In the example above, 'port' is the flag.

Flag functionality is provided by the pflag
library, a fork of the flag standard library
which maintains the same interface while adding POSIX compliance.

Installing

Using Cobra is easy. First, use go get to install the latest version
of the library.

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

Next, include Cobra in your application:

import "github.com/spf13/cobra"

Usage

cobra-cli is a command line program to generate cobra applications and command files.
It will bootstrap your application scaffolding to rapidly
develop a Cobra-based application. It is the easiest way to incorporate Cobra into your application.

It can be installed by running:

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

For complete details on using the Cobra-CLI generator, please read The Cobra Generator README

For complete details on using the Cobra library, please read The Cobra User Guide.

License

Cobra is released under the Apache 2.0 license. See LICENSE.txt

File: site/content/completions/_index.md Copy Chapter

Generating shell completions

Cobra can generate shell completions for multiple shells.
The currently supported shells are:

• Bash
• Zsh
• fish
• PowerShell

Cobra will automatically provide your program with a fully functional completion command,
similarly to how it provides the help command. If there are no other subcommands, the
default completion command will be hidden, but still functional.

Creating your own completion command Copy Chapter

If you do not wish to use the default completion command, you can choose to
provide your own, which will take precedence over the default one. (This also provides
backwards-compatibility with programs that already have their own completion command.)

If you are using the cobra-cli generator,
which can be found at spf13/cobra-cli,
you can create a completion command by running

cobra-cli add completion

and then modifying the generated cmd/completion.go file to look something like this
(writing the shell script to stdout allows the most flexible use):

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)
		}
	},
}

Note: The cobra generator may include messages printed to stdout, for example, if the config file is loaded; this will break the auto-completion script so must be removed.

Adapting the default completion command Copy Chapter

Cobra provides a few options for the default completion command. To configure such options you must set
the CompletionOptions field on the root command.

To tell Cobra not to provide the default completion command:

rootCmd.CompletionOptions.DisableDefaultCmd = true

To tell Cobra to mark the default completion command as hidden:

rootCmd.CompletionOptions.HiddenDefaultCmd = true

To tell Cobra not to provide the user with the --no-descriptions flag to the completion sub-commands:

rootCmd.CompletionOptions.DisableNoDescFlag = true

To tell Cobra to completely disable descriptions for completions:

rootCmd.CompletionOptions.DisableDescriptions = true

Customizing completions

The generated completion scripts will automatically handle completing commands and flags. However, you can make your completions much more powerful by providing information to complete your program's nouns and flag values.

Completion of nouns Copy Chapter

Static completion of nouns Copy Section

Cobra allows you to provide a pre-defined list of completion choices for your nouns using the ValidArgs field.
For example, if you want kubectl get [tab][tab] to show a list of valid "nouns" you have to set them.
Some simplified code from kubectl get looks like:

validArgs = []string{ "pod", "node", "service", "replicationcontroller" }

cmd := &cobra.Command{
	Use:     "get [(-o|--output=)json|yaml|template|...] (RESOURCE [NAME] | RESOURCE/NAME ...)",
	Short:   "Display one or many resources",
	Long:    get_long,
	Example: get_example,
	Run: func(cmd *cobra.Command, args []string) {
		cobra.CheckErr(RunGet(f, out, cmd, args))
	},
	ValidArgs: validArgs,
}

Notice we put the ValidArgs field on the get sub-command. Doing so will give results like:

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

Aliases for nouns

If your nouns have aliases, you can define them alongside ValidArgs using ArgAliases:

argAliases = []string { "pods", "nodes", "services", "svc", "replicationcontrollers", "rc" }

cmd := &cobra.Command{
    ...
	ValidArgs:  validArgs,
	ArgAliases: argAliases
}

The aliases are shown to the user on tab completion only if no completions were found within sub-commands or ValidArgs.

Dynamic completion of nouns Copy Section

In some cases it is not possible to provide a list of completions in advance. Instead, the list of completions must be determined at execution-time. In a similar fashion as for static completions, you can use the ValidArgsFunction field to provide a Go function that Cobra will execute when it needs the list of completion choices for the nouns of a command. Note that either ValidArgs or ValidArgsFunction can be used for a single cobra command, but not both.
Simplified code from helm status looks like:

cmd := &cobra.Command{
	Use:   "status RELEASE_NAME",
	Short: "Display the status of the named release",
	Long:  status_long,
	RunE: func(cmd *cobra.Command, args []string) {
		RunGet(args[0])
	},
	ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
		if len(args) != 0 {
			return nil, cobra.ShellCompDirectiveNoFileComp
		}
		return getReleasesFromCluster(toComplete), cobra.ShellCompDirectiveNoFileComp
	},
}

Where getReleasesFromCluster() is a Go function that obtains the list of current Helm releases running on the Kubernetes cluster.
Notice we put the ValidArgsFunction on the status sub-command. Let's assume the Helm releases on the cluster are: harbor, notary, rook and thanos then this dynamic completion will give results like:

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

You may have noticed the use of cobra.ShellCompDirective. These directives are bit fields allowing to control some shell completion behaviors for your particular completion. You can combine them with the bit-or operator such as cobra.ShellCompDirectiveNoSpace | cobra.ShellCompDirectiveNoFileComp

// Indicates that the shell will perform its default behavior after completions
// have been provided (this implies none of the other directives).
ShellCompDirectiveDefault

// Indicates an error occurred and completions should be ignored.
ShellCompDirectiveError

// Indicates that the shell should not add a space after the completion,
// even if there is a single completion provided.
ShellCompDirectiveNoSpace

// Indicates that the shell should not provide file completion even when
// no completion is provided.
ShellCompDirectiveNoFileComp

// Indicates that the returned completions should be used as file extension filters.
// For example, to complete only files of the form *.json or *.yaml:
//    return []cobra.Completion{"yaml", "json"}, cobra.ShellCompDirectiveFilterFileExt
// For flags, using MarkFlagFilename() and MarkPersistentFlagFilename()
// is a shortcut to using this directive explicitly.
//
ShellCompDirectiveFilterFileExt

// Indicates that only directory names should be provided in file completion.
// For example:
//    return nil, cobra.ShellCompDirectiveFilterDirs
// For flags, using MarkFlagDirname() is a shortcut to using this directive explicitly.
//
// To request directory names within another directory, the returned completions
// should specify a single directory name within which to search. For example,
// to complete directories within "themes/":
//    return []cobra.Completion{"themes"}, cobra.ShellCompDirectiveFilterDirs
//
ShellCompDirectiveFilterDirs

// ShellCompDirectiveKeepOrder indicates that the shell should preserve the order
// in which the completions are provided
ShellCompDirectiveKeepOrder

Note: When using the ValidArgsFunction, Cobra will call your registered function after having parsed all flags and arguments provided in the command-line. You therefore don't need to do this parsing yourself. For example, when a user calls helm status --namespace my-rook-ns [tab][tab], Cobra will call your registered ValidArgsFunction after having parsed the --namespace flag, as it would have done when calling the RunE function.

Debugging

Cobra achieves dynamic completion through the use of a hidden command called by the completion script. To debug your Go completion code, you can call this hidden command directly:

$ helm __complete status har<ENTER>
harbor
:4
Completion ended with directive: ShellCompDirectiveNoFileComp # This is on stderr

Important: If the noun to complete is empty (when the user has not yet typed any letters of that noun), you must pass an empty parameter to the __complete command:

$ helm __complete status ""<ENTER>
harbor
notary
rook
thanos
:4
Completion ended with directive: ShellCompDirectiveNoFileComp # This is on stderr

Calling the __complete command directly allows you to run the Go debugger to troubleshoot your code. You can also add printouts to your code; Cobra provides the following functions to use for printouts in Go completion code:

// Prints to the completion script debug file (if BASH_COMP_DEBUG_FILE
// is set to a file path) and optionally prints to stderr.
cobra.CompDebug(msg string, printToStdErr bool)
cobra.CompDebugln(msg string, printToStdErr bool)

// Prints to the completion script debug file (if BASH_COMP_DEBUG_FILE
// is set to a file path) and to stderr.
cobra.CompError(msg string)
cobra.CompErrorln(msg string)

Important: You should not leave traces that print directly to stdout in your completion code as they will be interpreted as completion choices by the completion script. Instead, use the cobra-provided debugging traces functions mentioned above.

Completions for flags Copy Chapter

Mark flags as required Copy Section

Most of the time completions will only show sub-commands. But if a flag is required to make a sub-command work, you probably want it to show up when the user types [tab][tab]. You can mark a flag as 'Required' like so:

cmd.MarkFlagRequired("pod")
cmd.MarkFlagRequired("container")

and you'll get something like

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

Specify dynamic flag completion Copy Section

As for nouns, Cobra provides a way of defining dynamic completion of flags. To provide a Go function that Cobra will execute when it needs the list of completion choices for a flag, you must register the function using the command.RegisterFlagCompletionFunc() function.

flagName := "output"
cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
	return []cobra.Completion{"json", "table", "yaml"}, cobra.ShellCompDirectiveDefault
})

Notice that calling RegisterFlagCompletionFunc() is done through the command with which the flag is associated. In our example this dynamic completion will give results like so:

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

Change the default ShellCompDirective

When no completion function is registered for a leaf command or for a flag, Cobra will
automatically use ShellCompDirectiveDefault, which will invoke the shell's filename completion.
This implies that when file completion does not apply to a leaf command or to a flag (the command
or flag does not operate on a filename), turning off file completion requires you to register a
completion function for that command/flag.
For example:

cmd.RegisterFlagCompletionFunc("flag-name", cobra.NoFileCompletions)

If you find that there are more situations where file completion should be turned off than
when it is applicable, you can recursively change the default ShellCompDirective for a command
and its subcommands to ShellCompDirectiveNoFileComp:

cmd.CompletionOptions.SetDefaultShellCompDirective(ShellCompDirectiveNoFileComp)

If doing so, keep in mind that you should instead register a completion function for leaf commands or
flags where file completion is applicable. For example:

cmd.RegisterFlagCompletionFunc("flag-name", cobra.FixedCompletions(nil, ShellCompDirectiveDefault))

To change the default directive for the entire program, set the DefaultShellCompDirective on the root command.

Debugging

You can also easily debug your Go completion code for flags:

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

Important: You should not leave traces that print to stdout in your completion code as they will be interpreted as completion choices by the completion script. Instead, use the cobra-provided debugging traces functions mentioned further above.

Specify valid filename extensions for flags that take a filename Copy Section

To limit completions of flag values to file names with certain extensions you can either use the different MarkFlagFilename() functions or a combination of RegisterFlagCompletionFunc() and ShellCompDirectiveFilterFileExt, like so:

flagName := "output"
cmd.MarkFlagFilename(flagName, "yaml", "json")

or

flagName := "output"
cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
	return []cobra.Completion{"yaml", "json"}, cobra.ShellCompDirectiveFilterFileExt})

Limit flag completions to directory names Copy Section

To limit completions of flag values to directory names you can either use the MarkFlagDirname() functions or a combination of RegisterFlagCompletionFunc() and ShellCompDirectiveFilterDirs, like so:

flagName := "output"
cmd.MarkFlagDirname(flagName)

or

flagName := "output"
cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
	return nil, cobra.ShellCompDirectiveFilterDirs
})

To limit completions of flag values to directory names within another directory you can use a combination of RegisterFlagCompletionFunc() and ShellCompDirectiveFilterDirs like so:

flagName := "output"
cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) {
	return []cobra.Completion{"themes"}, cobra.ShellCompDirectiveFilterDirs
})

Descriptions for completions Copy Section

Cobra provides support for completion descriptions. Such descriptions are supported for each shell
(however, for bash, it is only available in the completion V2 version).
For commands and flags, Cobra will provide the descriptions automatically, based on usage information.
For example, using zsh:

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

while using fish:

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

Cobra allows you to add descriptions to your own completions. Simply add the description text after each completion, following a \t separator. Cobra provides the helper function CompletionWithDesc(string, string) to create a completion with a description. This technique applies to completions returned by ValidArgs, ValidArgsFunction and RegisterFlagCompletionFunc(). For example:

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
}}

or

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

If you don't want to show descriptions in the completions, you can add --no-descriptions to the default completion command to disable them, like:

$ source <(helm completion bash)
$ helm completion [tab][tab]
bash        (generate autocompletion script for bash)        powershell  (generate autocompletion script for powershell)
fish        (generate autocompletion script for fish)        zsh         (generate autocompletion script for zsh)

$ source <(helm completion bash --no-descriptions)
$ helm completion [tab][tab]
bash        fish        powershell  zsh

Setting the _COMPLETION_DESCRIPTIONS environment variable (falling back to COBRA_COMPLETION_DESCRIPTIONS if empty or not set) to a falsey value achieves the same. `` is the name of your program with all non-ASCII-alphanumeric characters replaced by _.

Bash completions Copy Chapter

Dependencies Copy Section

The bash completion script generated by Cobra requires the bash_completion package. You should update the help text of your completion command to show how to install the bash_completion package (Kubectl docs)

Aliases Copy Section

You can also configure bash aliases for your program and they will also support completions.

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

Bash legacy dynamic completions Copy Section

For backward compatibility, Cobra still supports its bash legacy dynamic completion solution.
Please refer to Bash Completions for details.

Bash completion V2 Copy Section

Cobra provides two versions for bash completion. The original bash completion (which started it all!) can be used by calling
GenBashCompletion() or GenBashCompletionFile().

A new V2 bash completion version is also available. This version can be used by calling GenBashCompletionV2() or
GenBashCompletionFileV2(). The V2 version does not support the legacy dynamic completion
(see Bash Completions) but instead works only with the Go dynamic completion
solution described in this document.
Unless your program already uses the legacy dynamic completion solution, it is recommended that you use the bash
completion V2 solution which provides the following extra features:

• Supports completion descriptions (like the other shells)
• Small completion script of less than 300 lines (v1 generates scripts of thousands of lines; kubectl for example has a bash v1 completion script of over 13K lines)
• Streamlined user experience thanks to a completion behavior aligned with the other shells

Bash completion V2 supports descriptions for completions. When calling GenBashCompletionV2() or GenBashCompletionFileV2()
you must provide these functions with a parameter indicating if the completions should be annotated with a description; Cobra
will provide the description automatically based on usage information. You can choose to make this option configurable by
your users.

# 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

Note: Cobra's default completion command uses bash completion V2. If for some reason you need to use bash completion V1, you will need to implement your own completion command.

Zsh completions Copy Chapter

Cobra supports native zsh completion generated from the root cobra.Command.
The generated completion script should be put somewhere in your $fpath and be named
_<yourProgram>. You will need to start a new shell for the completions to become available.

Zsh supports descriptions for completions. Cobra will provide the description automatically,
based on usage information. Cobra provides a way to completely disable such descriptions by
using GenZshCompletionNoDesc() or GenZshCompletionFileNoDesc(). You can choose to make
this a configurable option to your users.

# 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

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

Note: Because of backward-compatibility requirements, we were forced to have a different API to disable completion descriptions between zsh and fish.

Limitations Copy Section

• Custom completions implemented in Bash scripting (legacy) are not supported and will be ignored for zsh (including the use of the BashCompCustom flag annotation).
  • You should instead use ValidArgsFunction and RegisterFlagCompletionFunc() which are portable to the different shells (bash, zsh, fish, powershell).
• The function MarkFlagCustom() is not supported and will be ignored for zsh.
  • You should instead use RegisterFlagCompletionFunc().

Zsh completions standardization Copy Section

Cobra 1.1 standardized its zsh completion support to align it with its other shell completions. Although the API was kept backward-compatible, some small changes in behavior were introduced.
Please refer to Zsh Completions for details.

fish completions Copy Chapter

Cobra supports native fish completions generated from the root cobra.Command. You can use the command.GenFishCompletion() or command.GenFishCompletionFile() functions. You must provide these functions with a parameter indicating if the completions should be annotated with a description; Cobra will provide the description automatically based on usage information. You can choose to make this option configurable by your users.

# 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)

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

Note: Because of backward-compatibility requirements, we were forced to have a different API to disable completion descriptions between zsh and fish.

Limitations Copy Section

• Custom completions implemented in bash scripting (legacy) are not supported and will be ignored for fish (including the use of the BashCompCustom flag annotation).
  • You should instead use ValidArgsFunction and RegisterFlagCompletionFunc() which are portable to the different shells (bash, zsh, fish, powershell).
• The function MarkFlagCustom() is not supported and will be ignored for fish.
  • You should instead use RegisterFlagCompletionFunc().
• The following flag completion annotations are not supported and will be ignored for fish:
  • BashCompFilenameExt (filtering by file extension)
  • BashCompSubdirsInDir (filtering by directory)
• The functions corresponding to the above annotations are consequently not supported and will be ignored for fish:
  • MarkFlagFilename() and MarkPersistentFlagFilename() (filtering by file extension)
  • MarkFlagDirname() and MarkPersistentFlagDirname() (filtering by directory)
• Similarly, the following completion directives are not supported and will be ignored for fish:
  • ShellCompDirectiveFilterFileExt (filtering by file extension)
  • ShellCompDirectiveFilterDirs (filtering by directory)

PowerShell completions Copy Chapter

Cobra supports native PowerShell completions generated from the root cobra.Command. You can use the command.GenPowerShellCompletion() or command.GenPowerShellCompletionFile() functions. To include descriptions use command.GenPowerShellCompletionWithDesc() and command.GenPowerShellCompletionFileWithDesc(). Cobra will provide the description automatically based on usage information. You can choose to make this option configurable by your users.

The script is designed to support all three PowerShell completion modes:

• TabCompleteNext (default windows style - on each key press the next option is displayed)
• Complete (works like bash)
• MenuComplete (works like zsh)

You set the mode with Set-PSReadLineKeyHandler -Key Tab -Function <mode>. Descriptions are only displayed when using the Complete or MenuComplete mode.

Users need PowerShell version 5.0 or above, which comes with Windows 10 and can be downloaded separately for Windows 7 or 8.1. They can then write the completions to a file and source this file from their PowerShell profile, which is referenced by the $Profile environment variable. See Get-Help about_Profiles for more info about PowerShell profiles.

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

# With descriptions and Mode 'MenuComplete' The description of the current selected value will be displayed below the suggestions.
$ helm s[tab]
search    show     status

search for a keyword in charts

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

Aliases Copy Section

You can also configure powershell aliases for your program and they will also support completions.

$ 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

The name of the completer block variable is of the form $__CompleterBlock where every - and : in the program name have been replaced with _, to respect powershell naming syntax.

Limitations Copy Section

• Custom completions implemented in bash scripting (legacy) are not supported and will be ignored for powershell (including the use of the BashCompCustom flag annotation).
  • You should instead use ValidArgsFunction and RegisterFlagCompletionFunc() which are portable to the different shells (bash, zsh, fish, powershell).
• The function MarkFlagCustom() is not supported and will be ignored for powershell.
  • You should instead use RegisterFlagCompletionFunc().
• The following flag completion annotations are not supported and will be ignored for powershell:
  • BashCompFilenameExt (filtering by file extension)
  • BashCompSubdirsInDir (filtering by directory)
• The functions corresponding to the above annotations are consequently not supported and will be ignored for powershell:
  • MarkFlagFilename() and MarkPersistentFlagFilename() (filtering by file extension)
  • MarkFlagDirname() and MarkPersistentFlagDirname() (filtering by directory)
• Similarly, the following completion directives are not supported and will be ignored for powershell:
  • ShellCompDirectiveFilterFileExt (filtering by file extension)
  • ShellCompDirectiveFilterDirs (filtering by directory)

File: site/content/completions/bash.md Copy Chapter

Generating Bash Completions For Your cobra.Command

Please refer to Shell Completions for details.

Bash legacy dynamic completions Copy Chapter

For backward compatibility, Cobra still supports its legacy dynamic completion solution (described below). Unlike the ValidArgsFunction solution, the legacy solution will only work for Bash shell-completion and not for other shells. This legacy solution can be used along-side ValidArgsFunction and RegisterFlagCompletionFunc(), as long as both solutions are not used for the same command. This provides a path to gradually migrate from the legacy solution to the new solution.

Note: Cobra's default completion command uses bash completion V2. If you are currently using Cobra's legacy dynamic completion solution, you should not use the default completion command but continue using your own.

The legacy solution allows you to inject bash functions into the bash completion script. Those bash functions are responsible for providing the completion choices for your own completions.

Some code that works in kubernetes:

const (
        bash_completion_func = `__kubectl_parse_get()
{
    local kubectl_output out
    if kubectl_output=$(kubectl get --no-headers "$1" 2>/dev/null); then
        out=($(echo "${kubectl_output}" | awk '{print $1}'))
        COMPREPLY=( $( compgen -W "${out[*]}" -- "$cur" ) )
    fi
}

__kubectl_get_resource()
{
    if [[ ${#nouns[@]} -eq 0 ]]; then
        return 1
    fi
    __kubectl_parse_get ${nouns[${#nouns[@]} -1]}
    if [[ $? -eq 0 ]]; then
        return 0
    fi
}

__kubectl_custom_func() {
    case ${last_command} in
        kubectl_get | kubectl_describe | kubectl_delete | kubectl_stop)
            __kubectl_get_resource
            return
            ;;
        *)
            ;;
    esac
}
`)

And then I set that in my command definition:

cmds := &cobra.Command{
	Use:   "kubectl",
	Short: "kubectl controls the Kubernetes cluster manager",
	Long: `kubectl controls the Kubernetes cluster manager.

Find more information at https://github.com/GoogleCloudPlatform/kubernetes.`,
	Run: runHelp,
	BashCompletionFunction: bash_completion_func,
}

The BashCompletionFunction option is really only valid/useful on the root command. Doing the above will cause __kubectl_custom_func() (__<command-use>_custom_func()) to be called when the built in processor was unable to find a solution. In the case of kubernetes a valid command might look something like kubectl get pod [mypod]. If you type kubectl get pod [tab][tab] the __kubectl_customc_func() will run because the cobra.Command only understood "kubectl" and "get." __kubectl_custom_func() will see that the cobra.Command is "kubectl_get" and will thus call another helper __kubectl_get_resource(). __kubectl_get_resource will look at the 'nouns' collected. In our example the only noun will be pod. So it will call __kubectl_parse_get pod. __kubectl_parse_get will actually call out to kubernetes and get any pods. It will then set COMPREPLY to valid pods!

Similarly, for flags:

annotation := make(map[string][]string)
	annotation[cobra.BashCompCustom] = []string{"__kubectl_get_namespaces"}

	flag := &pflag.Flag{
		Name:        "namespace",
		Usage:       usage,
		Annotations: annotation,
	}
	cmd.Flags().AddFlag(flag)

In addition add the __kubectl_get_namespaces implementation in the BashCompletionFunction
value, e.g.:

__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
}

File: site/content/completions/fish.md Copy Chapter

Generating Fish Completions For Your cobra.Command Copy Chapter

Please refer to Shell Completions for details.

File: site/content/completions/powershell.md Copy Chapter

Generating PowerShell Completions For Your Own cobra.Command

Please refer to Shell Completions for details.

File: site/content/completions/zsh.md Copy Chapter

Generating Zsh Completion For Your cobra.Command Copy Chapter

Please refer to Shell Completions for details.

Zsh completions standardization Copy Chapter

Cobra 1.1 standardized its zsh completion support to align it with its other shell completions. Although the API was kept backwards-compatible, some small changes in behavior were introduced.

Deprecation summary Copy Section

See further below for more details on these deprecations.

• cmd.MarkZshCompPositionalArgumentFile(pos, []string{}) is no longer needed. It is therefore deprecated and silently ignored.
• cmd.MarkZshCompPositionalArgumentFile(pos, glob[]) is deprecated and silently ignored.
  • Instead use ValidArgsFunction with ShellCompDirectiveFilterFileExt.
• cmd.MarkZshCompPositionalArgumentWords() is deprecated and silently ignored.
  • Instead use ValidArgsFunction.

Behavioral changes Copy Section

Noun completion

Flag-value completion

Improvements

• Custom completion support (ValidArgsFunction and RegisterFlagCompletionFunc())
• File completion by default if no other completions found
• Handling of required flags
• File extension filtering no longer mutually exclusive with bash usage
• Completion of directory names within another directory
• Support for = form of flags

File: site/content/docgen/_index.md Copy Chapter

Documentation generation

• Man page docs
• Markdown docs
• Rest docs
• Yaml docs

Options Copy Chapter

`DisableAutoGenTag` Copy Section

You may set cmd.DisableAutoGenTag = true
to entirely remove the auto generated string "Auto generated by spf13/cobra..."
from any documentation source.

`InitDefaultCompletionCmd` Copy Section

You may call cmd.InitDefaultCompletionCmd() to document the default autocompletion command.

File: site/content/docgen/man.md Copy Chapter

Generating Man Pages For Your Own cobra.Command

Generating man pages from a cobra command is incredibly easy. An example is as follows:

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)
	}
}

That will get you a man page /tmp/test.3

File: site/content/docgen/md.md Copy Chapter

Generating Markdown Docs For Your Own cobra.Command

Generating Markdown pages from a cobra command is incredibly easy. An example is as follows:

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)
	}
}

That will get you a Markdown document /tmp/test.md

Generate markdown docs for the entire command tree Copy Chapter

This program can actually generate docs for the kubectl command in the kubernetes project

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)
	}
}

This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")

Generate markdown docs for a single command Copy Chapter

You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to GenMarkdown instead of GenMarkdownTree

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

This will write the markdown doc for ONLY "cmd" into the out, buffer.

Customize the output Copy Chapter

Both GenMarkdown and GenMarkdownTree have alternate versions with callbacks to get some control of the output:

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

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

The filePrepender will prepend the return value given the full filepath to the rendered Markdown file. A common use case is to add front matter to use the generated documentation with Hugo:

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)
}

The linkHandler can be used to customize the rendered internal links to the commands, given a filename:

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

File: site/content/docgen/rest.md Copy Chapter

Generating ReStructured Text Docs For Your Own cobra.Command

Generating ReST pages from a cobra command is incredibly easy. An example is as follows:

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)
	}
}

That will get you a ReST document /tmp/test.rst

Generate ReST docs for the entire command tree Copy Chapter

This program can actually generate docs for the kubectl command in the kubernetes project

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)
	}
}

This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")

Generate ReST docs for a single command Copy Chapter

You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to GenReST instead of GenReSTTree

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

This will write the ReST doc for ONLY "cmd" into the out, buffer.

Customize the output Copy Chapter

Both GenReST and GenReSTTree have alternate versions with callbacks to get some control of the output:

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

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

The filePrepender will prepend the return value given the full filepath to the rendered ReST file. A common use case is to add front matter to use the generated documentation with Hugo:

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)
}

The linkHandler can be used to customize the rendered links to the commands, given a command name and reference. This is useful while converting rst to html or while generating documentation with tools like Sphinx where :ref: is used:

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