120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
# Cobra Shell Completions Reference
|
|
|
|
Cobra generates shell completion scripts for bash, zsh, fish, and PowerShell automatically. Subcommand names and flag names are completed for free. You add completions for flag values and positional arguments.
|
|
|
|
## Built-in completion command
|
|
|
|
Cobra registers a `completion` subcommand automatically:
|
|
|
|
```bash
|
|
myapp completion bash # generate bash script
|
|
myapp completion zsh # generate zsh script
|
|
myapp completion fish # generate fish script
|
|
myapp completion powershell
|
|
|
|
# Install (example for zsh):
|
|
myapp completion zsh > "${fpath[1]}/_myapp"
|
|
```
|
|
|
|
## ShellCompDirective
|
|
|
|
The `ShellCompDirective` controls shell behavior after your completion function returns:
|
|
|
|
| Directive | Meaning |
|
|
| --- | --- |
|
|
| `ShellCompDirectiveDefault` | Fall back to file completion after your results |
|
|
| `ShellCompDirectiveNoFileComp` | Disable file completion fallback |
|
|
| `ShellCompDirectiveNoSpace` | Don't add a space after the completion |
|
|
| `ShellCompDirectiveFilterFileExt(exts)` | Only show files with given extensions |
|
|
| `ShellCompDirectiveFilterDirs(dirs)` | Only show directories |
|
|
| `ShellCompDirectiveError` | Signal an error (show no completions) |
|
|
|
|
Combine with bitwise OR: `cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace`.
|
|
|
|
Use `ShellCompDirectiveNoFileComp` whenever your list is exhaustive — it prevents the shell from appending irrelevant files.
|
|
|
|
## Static arg completions
|
|
|
|
```go
|
|
var getCmd = &cobra.Command{
|
|
Use: "get <resource>",
|
|
ValidArgs: []string{"pod", "service", "deployment", "configmap"},
|
|
Args: cobra.OnlyValidArgs,
|
|
RunE: func(cmd *cobra.Command, args []string) error { /* ... */ },
|
|
}
|
|
```
|
|
|
|
## Dynamic arg completions
|
|
|
|
```go
|
|
var getCmd = &cobra.Command{
|
|
ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
|
|
if len(args) > 0 {
|
|
// first arg already provided — no more completions
|
|
return nil, cobra.ShellCompDirectiveNoFileComp
|
|
}
|
|
resources, err := listResources(toComplete)
|
|
if err != nil {
|
|
return nil, cobra.ShellCompDirectiveError
|
|
}
|
|
return resources, cobra.ShellCompDirectiveNoFileComp
|
|
},
|
|
}
|
|
```
|
|
|
|
`toComplete` is the prefix the user has typed so far — filter your results by it for responsive completions.
|
|
|
|
## Flag value completions
|
|
|
|
```go
|
|
func init() {
|
|
rootCmd.RegisterFlagCompletionFunc("output", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
|
|
return []string{"json\tJSON output", "yaml\tYAML output", "table\tTable output"}, cobra.ShellCompDirectiveNoFileComp
|
|
})
|
|
|
|
rootCmd.RegisterFlagCompletionFunc("namespace", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
|
|
ns, err := listNamespaces()
|
|
if err != nil {
|
|
return nil, cobra.ShellCompDirectiveError
|
|
}
|
|
return ns, cobra.ShellCompDirectiveNoFileComp
|
|
})
|
|
}
|
|
```
|
|
|
|
Descriptions after `\t` are shown in zsh and fish menus.
|
|
|
|
## Completion annotations
|
|
|
|
Mark a flag to complete as a file or directory:
|
|
|
|
```go
|
|
cmd.Flags().String("config", "", "config file")
|
|
cmd.MarkFlagFilename("config", "yaml", "yml", "json") // only those extensions
|
|
|
|
cmd.Flags().String("dir", "", "output directory")
|
|
cmd.MarkFlagDirname("dir")
|
|
```
|
|
|
|
## Testing completions
|
|
|
|
```go
|
|
func TestCompletion(t *testing.T) {
|
|
rootCmd.SetArgs([]string{"__complete", "get", ""})
|
|
buf := new(bytes.Buffer)
|
|
rootCmd.SetOut(buf)
|
|
rootCmd.Execute()
|
|
assert.Contains(t, buf.String(), "pod")
|
|
assert.Contains(t, buf.String(), "service")
|
|
}
|
|
```
|
|
|
|
`__complete` is cobra's internal completion request verb. Pass the partial args as additional arguments.
|
|
|
|
## Disabling the completion command
|
|
|
|
```go
|
|
rootCmd.CompletionOptions.DisableDefaultCmd = true // remove the completion subcommand
|
|
rootCmd.CompletionOptions.HiddenDefaultCmd = true // keep it but hide from help
|
|
```
|