mirror of
https://github.com/spf13/cobra
synced 2024-11-24 14:47:12 +00:00
site: rework structure and headers
This commit is contained in:
umarcor
parent
a3c9f45b00
commit
9c878d49b1
18 changed files with 1046 additions and 334 deletions
130
README.md
130
README.md
|
|
@ -1,112 +1,24 @@
|
||||||
|
<p align="center">
|
||||||
|
<a title="cobra.dev" href="https://cobra.dev/"><img width="550px" src="site/static/images/logo.png"/></a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a title="Site" href="https://cobra.dev/"><img src="https://img.shields.io/website.svg?label=cobra.dev&longCache=true&style=flat-square&url=http%3A%2F%2Fcobra.dev%2Findex.html"></a><!--
|
||||||
|
-->
|
||||||
|
<a title="Slack" href="https://gophers.slack.com/archives/CD3LP1199"><img alt="Slack" src="https://img.shields.io/badge/Slack-cobra-brightgreen?longCache=true&label=slack&logo=slack&logoColor=fff"></a><!--
|
||||||
|
-->
|
||||||
|
<a title="GoDoc" href="https://godoc.org/github.com/spf13/cobra"><img alt="GoDoc" src="https://godoc.org/github.com/spf13/cobra?status.svg"></a><!--
|
||||||
|
-->
|
||||||
|
<a title="Go Report Card" href="https://goreportcard.com/report/github.com/spf13/cobra"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/spf13/cobra"></a><!--
|
||||||
|
-->
|
||||||
|
<a title="Continuous Integration" href="https://github.com/spf13/cobra/actions/workflows/test.yml"><img alt="GitHub release (latest by date including pre-releases)" src="https://img.shields.io/github/actions/workflow/status/spf13/cobra/test.yml?branch=main&longCache=true&label=Test&logo=github%20actions&logoColor=fff"></a><!--
|
||||||
|
-->
|
||||||
|
<a title="Releases" href="https://github.com/spf13/cobra/releases"><img alt="GitHub release (latest by date including pre-releases)" src="https://img.shields.io/github/v/release/spf13/cobra?include_prereleases&longCache=true&label=Releases&logo=github&color=informational"></a><!--
|
||||||
|
-->
|
||||||
|
</p>
|
||||||
|
|
||||||
Cobra is a library for creating powerful modern CLI applications.
|
Cobra is a library for creating powerful modern CLI applications.
|
||||||
|
|
||||||
Cobra is used in many Go projects such as [Kubernetes](https://kubernetes.io/),
|
Cobra is used in many Go projects such as [Kubernetes](http://kubernetes.io/),
|
||||||
[Hugo](https://gohugo.io), and [GitHub CLI](https://github.com/cli/cli) to
|
[Hugo](https://gohugo.io), and [Github CLI](https://github.com/cli/cli) to
|
||||||
name a few. [This list](site/content/projects_using_cobra.md) contains a more extensive list of projects using Cobra.
|
name a few. [This list](./site/content/projects_using_cobra.md) contains a more extensive list of projects using Cobra.
|
||||||
|
|
||||||
[](https://github.com/spf13/cobra/actions?query=workflow%3ATest)
|
|
||||||
[](https://pkg.go.dev/github.com/spf13/cobra)
|
|
||||||
[](https://goreportcard.com/report/github.com/spf13/cobra)
|
|
||||||
[](https://gophers.slack.com/archives/CD3LP1199)
|
|
||||||
|
|
||||||
# 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](https://github.com/spf13/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
|
|
||||||
|
|
||||||
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](https://pkg.go.dev/github.com/spf13/cobra#Command)
|
|
||||||
|
|
||||||
## Flags
|
|
||||||
|
|
||||||
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](https://golang.org/pkg/flag/).
|
|
||||||
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](https://github.com/spf13/pflag), 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:
|
|
||||||
|
|
||||||
```go
|
|
||||||
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](https://github.com/spf13/cobra-cli/blob/main/README.md)
|
|
||||||
|
|
||||||
For complete details on using the Cobra library, please read the [The Cobra User Guide](site/content/user_guide.md).
|
|
||||||
|
|
||||||
# License
|
|
||||||
|
|
||||||
Cobra is released under the Apache 2.0 license. See [LICENSE.txt](LICENSE.txt)
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,8 @@
|
||||||
# Generating shell completions
|
---
|
||||||
|
weight: 10
|
||||||
|
---
|
||||||
|
|
||||||
|
# Shell completions
|
||||||
|
|
||||||
Cobra can generate shell completions for multiple shells.
|
Cobra can generate shell completions for multiple shells.
|
||||||
The currently supported shells are:
|
The currently supported shells are:
|
||||||
|
|
@ -114,13 +118,13 @@ To tell Cobra to completely disable descriptions for completions:
|
||||||
rootCmd.CompletionOptions.DisableDescriptions = true
|
rootCmd.CompletionOptions.DisableDescriptions = true
|
||||||
```
|
```
|
||||||
|
|
||||||
# Customizing completions
|
## 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.
|
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
|
### Completion of nouns
|
||||||
|
|
||||||
### Static completion of nouns
|
#### Static completion of nouns
|
||||||
|
|
||||||
Cobra allows you to provide a pre-defined list of completion choices for your nouns using the `ValidArgs` field.
|
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.
|
For example, if you want `kubectl get [tab][tab]` to show a list of valid "nouns" you have to set them.
|
||||||
|
|
@ -148,7 +152,7 @@ $ kubectl get [tab][tab]
|
||||||
node pod replicationcontroller service
|
node pod replicationcontroller service
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Aliases for nouns
|
##### Aliases for nouns
|
||||||
|
|
||||||
If your nouns have aliases, you can define them alongside `ValidArgs` using `ArgAliases`:
|
If your nouns have aliases, you can define them alongside `ValidArgs` using `ArgAliases`:
|
||||||
|
|
||||||
|
|
@ -164,7 +168,7 @@ cmd := &cobra.Command{
|
||||||
|
|
||||||
The aliases are shown to the user on tab completion only if no completions were found within sub-commands or `ValidArgs`.
|
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
|
#### Dynamic completion of nouns
|
||||||
|
|
||||||
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.
|
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:
|
Simplified code from `helm status` looks like:
|
||||||
|
|
@ -236,7 +240,7 @@ 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.
|
***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
|
##### 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:
|
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:
|
||||||
```bash
|
```bash
|
||||||
|
|
@ -269,9 +273,9 @@ 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.
|
***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
|
### Completions for flags
|
||||||
|
|
||||||
### Mark flags as required
|
#### Mark flags as required
|
||||||
|
|
||||||
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:
|
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:
|
||||||
|
|
||||||
|
|
@ -287,7 +291,7 @@ $ kubectl exec [tab][tab]
|
||||||
-c --container= -p --pod=
|
-c --container= -p --pod=
|
||||||
```
|
```
|
||||||
|
|
||||||
### Specify dynamic flag completion
|
#### Specify dynamic flag completion
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
|
|
@ -304,7 +308,7 @@ $ helm status --output [tab][tab]
|
||||||
json table yaml
|
json table yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Debugging
|
##### Debugging
|
||||||
|
|
||||||
You can also easily debug your Go completion code for flags:
|
You can also easily debug your Go completion code for flags:
|
||||||
```bash
|
```bash
|
||||||
|
|
@ -317,7 +321,7 @@ Completion ended with directive: ShellCompDirectiveNoFileComp # This is on stder
|
||||||
```
|
```
|
||||||
***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.
|
***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
|
#### Specify valid filename extensions for flags that take a filename
|
||||||
|
|
||||||
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:
|
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:
|
||||||
```go
|
```go
|
||||||
|
|
@ -331,7 +335,7 @@ cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string,
|
||||||
return []string{"yaml", "json"}, ShellCompDirectiveFilterFileExt})
|
return []string{"yaml", "json"}, ShellCompDirectiveFilterFileExt})
|
||||||
```
|
```
|
||||||
|
|
||||||
### Limit flag completions to directory names
|
#### Limit flag completions to directory names
|
||||||
|
|
||||||
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:
|
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:
|
||||||
```go
|
```go
|
||||||
|
|
@ -352,7 +356,7 @@ cmd.RegisterFlagCompletionFunc(flagName, func(cmd *cobra.Command, args []string,
|
||||||
return []string{"themes"}, cobra.ShellCompDirectiveFilterDirs
|
return []string{"themes"}, cobra.ShellCompDirectiveFilterDirs
|
||||||
})
|
})
|
||||||
```
|
```
|
||||||
### Descriptions for completions
|
#### Descriptions for completions
|
||||||
|
|
||||||
Cobra provides support for completion descriptions. Such descriptions are supported for each shell
|
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](#bash-completion-v2)).
|
(however, for bash, it is only available in the [completion V2 version](#bash-completion-v2)).
|
||||||
|
|
@ -393,184 +397,3 @@ $ source <(helm completion bash --no-descriptions)
|
||||||
$ helm completion [tab][tab]
|
$ helm completion [tab][tab]
|
||||||
bash fish powershell zsh
|
bash fish powershell zsh
|
||||||
```
|
```
|
||||||
## Bash completions
|
|
||||||
|
|
||||||
### Dependencies
|
|
||||||
|
|
||||||
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](https://kubernetes.io/docs/tasks/tools/install-kubectl/#enabling-shell-autocompletion))
|
|
||||||
|
|
||||||
### Aliases
|
|
||||||
|
|
||||||
You can also configure `bash` aliases for your program and they will also support completions.
|
|
||||||
|
|
||||||
```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
|
|
||||||
```
|
|
||||||
### Bash legacy dynamic completions
|
|
||||||
|
|
||||||
For backward compatibility, Cobra still supports its bash legacy dynamic completion solution.
|
|
||||||
Please refer to [Bash Completions](bash.md) for details.
|
|
||||||
|
|
||||||
### Bash completion V2
|
|
||||||
|
|
||||||
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](bash.md)) 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
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
* 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
|
|
||||||
|
|
||||||
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](zsh.md) for details.
|
|
||||||
|
|
||||||
## fish completions
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
* 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
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
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 `$__<programName>CompleterBlock` where every `-` and `:` in the program name have been replaced with `_`, to respect powershell naming syntax.
|
|
||||||
|
|
||||||
### Limitations
|
|
||||||
|
|
||||||
* 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)
|
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,65 @@
|
||||||
# Generating Bash Completions For Your cobra.Command
|
---
|
||||||
|
weight: 11
|
||||||
|
---
|
||||||
|
|
||||||
Please refer to [Shell Completions](_index.md) for details.
|
## Bash completions
|
||||||
|
|
||||||
## Bash legacy dynamic completions
|
#### Dependencies
|
||||||
|
|
||||||
|
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](https://kubernetes.io/docs/tasks/tools/install-kubectl/#enabling-shell-autocompletion))
|
||||||
|
|
||||||
|
#### Aliases
|
||||||
|
|
||||||
|
You can also configure `bash` aliases for your program and they will also support completions.
|
||||||
|
|
||||||
|
```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
|
||||||
|
```
|
||||||
|
#### Bash legacy dynamic completions
|
||||||
|
|
||||||
|
For backward compatibility, Cobra still supports its bash legacy dynamic completion solution.
|
||||||
|
Please refer to [Bash Completions](bash.md) for details.
|
||||||
|
|
||||||
|
### Bash completion V2
|
||||||
|
|
||||||
|
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](bash.md)) 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.
|
||||||
|
|
||||||
|
### Bash legacy dynamic completions
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,33 @@
|
||||||
## Generating Fish Completions For Your cobra.Command
|
---
|
||||||
|
weight: 12
|
||||||
|
---
|
||||||
|
|
||||||
Please refer to [Shell Completions](_index.md) for details.
|
# Fish completions
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
* 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)
|
||||||
|
|
|
||||||
|
|
@ -1,3 +1,80 @@
|
||||||
# Generating PowerShell Completions For Your Own cobra.Command
|
---
|
||||||
|
weight: 13
|
||||||
|
---
|
||||||
|
|
||||||
Please refer to [Shell Completions](_index.md#powershell-completions) for details.
|
# PowerShell completions
|
||||||
|
|
||||||
|
Cobra can generate PowerShell completion scripts. 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.
|
||||||
|
|
||||||
|
*Note*: PowerShell completions have not (yet?) been aligned to Cobra's generic shell completion support. This implies the PowerShell completions are not as rich as for other shells (see [What's not yet supported](#whats-not-yet-supported)), and may behave slightly differently. They are still very useful for PowerShell users.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
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 `$__<programName>CompleterBlock` where every `-` and `:` in the program name have been replaced with `_`, to respect powershell naming syntax.
|
||||||
|
|
||||||
|
## Limitations
|
||||||
|
|
||||||
|
* 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)
|
||||||
|
|
||||||
|
## What's supported
|
||||||
|
|
||||||
|
- Completion for subcommands using their `.Short` description
|
||||||
|
- Completion for non-hidden flags using their `.Name` and `.Shorthand`
|
||||||
|
|
||||||
|
## What's not yet supported
|
||||||
|
|
||||||
|
- Command aliases
|
||||||
|
- Required, filename or custom flags (they will work like normal flags)
|
||||||
|
- Custom completion scripts
|
||||||
|
|
|
||||||
|
|
@ -1,12 +1,48 @@
|
||||||
## Generating Zsh Completion For Your cobra.Command
|
---
|
||||||
|
weight: 14
|
||||||
|
---
|
||||||
|
|
||||||
|
# Zsh completions
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
* 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
|
||||||
|
|
||||||
|
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](zsh.md) for details.
|
||||||
|
|
||||||
Please refer to [Shell Completions](_index.md) for details.
|
|
||||||
|
|
||||||
## Zsh completions standardization
|
## Zsh completions standardization
|
||||||
|
|
||||||
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.
|
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
|
## Deprecation summary
|
||||||
|
|
||||||
See further below for more details on these deprecations.
|
See further below for more details on these deprecations.
|
||||||
|
|
||||||
|
|
@ -16,9 +52,10 @@ See further below for more details on these deprecations.
|
||||||
* `cmd.MarkZshCompPositionalArgumentWords()` is **deprecated** and silently ignored.
|
* `cmd.MarkZshCompPositionalArgumentWords()` is **deprecated** and silently ignored.
|
||||||
* Instead use `ValidArgsFunction`.
|
* Instead use `ValidArgsFunction`.
|
||||||
|
|
||||||
### Behavioral changes
|
## Behavioral changes
|
||||||
|
|
||||||
|
### Noun completion*
|
||||||
|
|
||||||
**Noun completion**
|
|
||||||
|Old behavior|New behavior|
|
|Old behavior|New behavior|
|
||||||
|---|---|
|
|---|---|
|
||||||
|No file completion by default (opposite of bash)|File completion by default; use `ValidArgsFunction` with `ShellCompDirectiveNoFileComp` to turn off file completion on a per-argument basis|
|
|No file completion by default (opposite of bash)|File completion by default; use `ValidArgsFunction` with `ShellCompDirectiveNoFileComp` to turn off file completion on a per-argument basis|
|
||||||
|
|
@ -27,7 +64,7 @@ See further below for more details on these deprecations.
|
||||||
|`cmd.MarkZshCompPositionalArgumentFile(pos, glob[])` used to turn on file completion **with glob filtering** on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentFile()` is **deprecated** and silently ignored; use `ValidArgsFunction` with `ShellCompDirectiveFilterFileExt` for file **extension** filtering (not full glob filtering)|
|
|`cmd.MarkZshCompPositionalArgumentFile(pos, glob[])` used to turn on file completion **with glob filtering** on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentFile()` is **deprecated** and silently ignored; use `ValidArgsFunction` with `ShellCompDirectiveFilterFileExt` for file **extension** filtering (not full glob filtering)|
|
||||||
|`cmd.MarkZshCompPositionalArgumentWords(pos, words[])` used to provide completion choices on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentWords()` is **deprecated** and silently ignored; use `ValidArgsFunction` to achieve the same behavior|
|
|`cmd.MarkZshCompPositionalArgumentWords(pos, words[])` used to provide completion choices on a per-argument position basis (zsh-specific)|`cmd.MarkZshCompPositionalArgumentWords()` is **deprecated** and silently ignored; use `ValidArgsFunction` to achieve the same behavior|
|
||||||
|
|
||||||
**Flag-value completion**
|
### Flag-value completion
|
||||||
|
|
||||||
|Old behavior|New behavior|
|
|Old behavior|New behavior|
|
||||||
|---|---|
|
|---|---|
|
||||||
|
|
@ -38,7 +75,7 @@ See further below for more details on these deprecations.
|
||||||
|Completion of a flag name does not repeat, unless flag is of type `*Array` or `*Slice` (not supported by bash)|Retained for `zsh` and added to `fish`|
|
|Completion of a flag name does not repeat, unless flag is of type `*Array` or `*Slice` (not supported by bash)|Retained for `zsh` and added to `fish`|
|
||||||
|Completion of a flag name does not provide the `=` form (unlike bash)|Retained for `zsh` and added to `fish`|
|
|Completion of a flag name does not provide the `=` form (unlike bash)|Retained for `zsh` and added to `fish`|
|
||||||
|
|
||||||
**Improvements**
|
## Improvements
|
||||||
|
|
||||||
* Custom completion support (`ValidArgsFunction` and `RegisterFlagCompletionFunc()`)
|
* Custom completion support (`ValidArgsFunction` and `RegisterFlagCompletionFunc()`)
|
||||||
* File completion by default if no other completions found
|
* File completion by default if no other completions found
|
||||||
|
|
|
||||||
50
site/content/concepts.md
Normal file
50
site/content/concepts.md
Normal file
|
|
@ -0,0 +1,50 @@
|
||||||
|
---
|
||||||
|
weight: 2
|
||||||
|
---
|
||||||
|
|
||||||
|
# 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
|
||||||
|
|
||||||
|
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](https://godoc.org/github.com/spf13/cobra#Command)
|
||||||
|
|
||||||
|
## Flags
|
||||||
|
|
||||||
|
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](https://golang.org/pkg/flag/).
|
||||||
|
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](https://github.com/spf13/pflag), a fork of the flag standard library
|
||||||
|
which maintains the same interface while adding POSIX compliance.
|
||||||
|
|
@ -1,3 +1,7 @@
|
||||||
|
---
|
||||||
|
weight: 30
|
||||||
|
---
|
||||||
|
|
||||||
# Contributing to Cobra
|
# Contributing to Cobra
|
||||||
|
|
||||||
Thank you so much for contributing to Cobra. We appreciate your time and help.
|
Thank you so much for contributing to Cobra. We appreciate your time and help.
|
||||||
|
|
@ -1,3 +1,7 @@
|
||||||
|
---
|
||||||
|
weight: 20
|
||||||
|
---
|
||||||
|
|
||||||
# Documentation generation
|
# Documentation generation
|
||||||
|
|
||||||
- [Man page docs](man.md)
|
- [Man page docs](man.md)
|
||||||
|
|
@ -6,11 +10,11 @@
|
||||||
- [Yaml docs](yaml.md)
|
- [Yaml docs](yaml.md)
|
||||||
|
|
||||||
## Options
|
## Options
|
||||||
|
|
||||||
### `DisableAutoGenTag`
|
### `DisableAutoGenTag`
|
||||||
|
|
||||||
You may set `cmd.DisableAutoGenTag = true`
|
You may set `cmd.DisableAutoGenTag = true` to _entirely_ remove the auto generated string
|
||||||
to _entirely_ remove the auto generated string "Auto generated by spf13/cobra..."
|
"Auto generated by spf13/cobra..." from any documentation source.
|
||||||
from any documentation source.
|
|
||||||
|
|
||||||
### `InitDefaultCompletionCmd`
|
### `InitDefaultCompletionCmd`
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,8 @@
|
||||||
# Generating Man Pages For Your Own cobra.Command
|
---
|
||||||
|
weight: 21
|
||||||
|
---
|
||||||
|
|
||||||
|
## Man Pages
|
||||||
|
|
||||||
Generating man pages from a cobra command is incredibly easy. An example is as follows:
|
Generating man pages from a cobra command is incredibly easy. An example is as follows:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,8 @@
|
||||||
# Generating Markdown Docs For Your Own cobra.Command
|
---
|
||||||
|
weight: 22
|
||||||
|
---
|
||||||
|
|
||||||
|
## Markdown Docs
|
||||||
|
|
||||||
Generating Markdown pages from a cobra command is incredibly easy. An example is as follows:
|
Generating Markdown pages from a cobra command is incredibly easy. An example is as follows:
|
||||||
|
|
||||||
|
|
@ -26,7 +30,7 @@ func main() {
|
||||||
|
|
||||||
That will get you a Markdown document `/tmp/test.md`
|
That will get you a Markdown document `/tmp/test.md`
|
||||||
|
|
||||||
## Generate markdown docs for the entire command tree
|
### The entire command tree
|
||||||
|
|
||||||
This program can actually generate docs for the kubectl command in the kubernetes project
|
This program can actually generate docs for the kubectl command in the kubernetes project
|
||||||
|
|
||||||
|
|
@ -55,7 +59,7 @@ func main() {
|
||||||
|
|
||||||
This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
|
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
|
### For a single command
|
||||||
|
|
||||||
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`
|
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`
|
||||||
|
|
||||||
|
|
@ -69,7 +73,7 @@ You may wish to have more control over the output, or only generate for a single
|
||||||
|
|
||||||
This will write the markdown doc for ONLY "cmd" into the out, buffer.
|
This will write the markdown doc for ONLY "cmd" into the out, buffer.
|
||||||
|
|
||||||
## Customize the output
|
### Customize the output
|
||||||
|
|
||||||
Both `GenMarkdown` and `GenMarkdownTree` have alternate versions with callbacks to get some control of the output:
|
Both `GenMarkdown` and `GenMarkdownTree` have alternate versions with callbacks to get some control of the output:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,8 @@
|
||||||
# Generating ReStructured Text Docs For Your Own cobra.Command
|
---
|
||||||
|
weight: 23
|
||||||
|
---
|
||||||
|
|
||||||
|
## ReStructured Text Docs
|
||||||
|
|
||||||
Generating ReST pages from a cobra command is incredibly easy. An example is as follows:
|
Generating ReST pages from a cobra command is incredibly easy. An example is as follows:
|
||||||
|
|
||||||
|
|
@ -26,7 +30,7 @@ func main() {
|
||||||
|
|
||||||
That will get you a ReST document `/tmp/test.rst`
|
That will get you a ReST document `/tmp/test.rst`
|
||||||
|
|
||||||
## Generate ReST docs for the entire command tree
|
### The entire command tree
|
||||||
|
|
||||||
This program can actually generate docs for the kubectl command in the kubernetes project
|
This program can actually generate docs for the kubectl command in the kubernetes project
|
||||||
|
|
||||||
|
|
@ -55,7 +59,7 @@ func main() {
|
||||||
|
|
||||||
This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
|
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
|
### For a single command
|
||||||
|
|
||||||
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`
|
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`
|
||||||
|
|
||||||
|
|
@ -69,7 +73,7 @@ You may wish to have more control over the output, or only generate for a single
|
||||||
|
|
||||||
This will write the ReST doc for ONLY "cmd" into the out, buffer.
|
This will write the ReST doc for ONLY "cmd" into the out, buffer.
|
||||||
|
|
||||||
## Customize the output
|
### Customize the output
|
||||||
|
|
||||||
Both `GenReST` and `GenReSTTree` have alternate versions with callbacks to get some control of the output:
|
Both `GenReST` and `GenReSTTree` have alternate versions with callbacks to get some control of the output:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,8 @@
|
||||||
# Generating Yaml Docs For Your Own cobra.Command
|
---
|
||||||
|
weight: 24
|
||||||
|
---
|
||||||
|
|
||||||
|
## Yaml Docs
|
||||||
|
|
||||||
Generating yaml files from a cobra command is incredibly easy. An example is as follows:
|
Generating yaml files from a cobra command is incredibly easy. An example is as follows:
|
||||||
|
|
||||||
|
|
@ -26,7 +30,7 @@ func main() {
|
||||||
|
|
||||||
That will get you a Yaml document `/tmp/test.yaml`
|
That will get you a Yaml document `/tmp/test.yaml`
|
||||||
|
|
||||||
## Generate yaml docs for the entire command tree
|
### The entire command tree
|
||||||
|
|
||||||
This program can actually generate docs for the kubectl command in the kubernetes project
|
This program can actually generate docs for the kubectl command in the kubernetes project
|
||||||
|
|
||||||
|
|
@ -55,7 +59,7 @@ func main() {
|
||||||
|
|
||||||
This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
|
This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./")
|
||||||
|
|
||||||
## Generate yaml docs for a single command
|
### For a single command
|
||||||
|
|
||||||
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 `GenYaml` instead of `GenYamlTree`
|
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 `GenYaml` instead of `GenYamlTree`
|
||||||
|
|
||||||
|
|
@ -66,7 +70,7 @@ You may wish to have more control over the output, or only generate for a single
|
||||||
|
|
||||||
This will write the yaml doc for ONLY "cmd" into the out, buffer.
|
This will write the yaml doc for ONLY "cmd" into the out, buffer.
|
||||||
|
|
||||||
## Customize the output
|
### Customize the output
|
||||||
|
|
||||||
Both `GenYaml` and `GenYamlTree` have alternate versions with callbacks to get some control of the output:
|
Both `GenYaml` and `GenYamlTree` have alternate versions with callbacks to get some control of the output:
|
||||||
|
|
||||||
|
|
|
||||||
648
site/content/getting_started.md
Normal file
648
site/content/getting_started.md
Normal file
|
|
@ -0,0 +1,648 @@
|
||||||
|
---
|
||||||
|
weight: 4
|
||||||
|
---
|
||||||
|
|
||||||
|
# Getting Started
|
||||||
|
|
||||||
|
While you are welcome to provide your own organization, typically a Cobra-based
|
||||||
|
application will follow the following organizational structure:
|
||||||
|
|
||||||
|
```
|
||||||
|
▾ appName/
|
||||||
|
▾ cmd/
|
||||||
|
add.go
|
||||||
|
your.go
|
||||||
|
commands.go
|
||||||
|
here.go
|
||||||
|
main.go
|
||||||
|
```
|
||||||
|
|
||||||
|
In a Cobra app, typically the main.go file is very bare. It serves one purpose: to initialize Cobra.
|
||||||
|
|
||||||
|
```go
|
||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"{pathToYourApp}/cmd"
|
||||||
|
)
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
cmd.Execute()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Using the Cobra Generator
|
||||||
|
|
||||||
|
Cobra provides its own program that will create your application and add any
|
||||||
|
commands you want. It's the easiest way to incorporate Cobra into your application.
|
||||||
|
|
||||||
|
[Here](https://github.com/spf13/cobra/blob/master/cobra/README.md) you can find more information about it.
|
||||||
|
|
||||||
|
## Using the Cobra Library
|
||||||
|
|
||||||
|
To manually implement Cobra you need to create a bare main.go file and a rootCmd file.
|
||||||
|
You will optionally provide additional commands as you see fit.
|
||||||
|
|
||||||
|
### Create rootCmd
|
||||||
|
|
||||||
|
Cobra doesn't require any special constructors. Simply create your commands.
|
||||||
|
|
||||||
|
Ideally you place this in app/cmd/root.go:
|
||||||
|
|
||||||
|
```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 http://hugo.spf13.com`,
|
||||||
|
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)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
You will additionally define flags and handle configuration in your init() function.
|
||||||
|
|
||||||
|
For example cmd/root.go:
|
||||||
|
|
||||||
|
```go
|
||||||
|
package cmd
|
||||||
|
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
"os"
|
||||||
|
|
||||||
|
homedir "github.com/mitchellh/go-homedir"
|
||||||
|
"github.com/spf13/cobra"
|
||||||
|
"github.com/spf13/viper"
|
||||||
|
)
|
||||||
|
|
||||||
|
var (
|
||||||
|
// Used for flags.
|
||||||
|
cfgFile string
|
||||||
|
userLicense string
|
||||||
|
|
||||||
|
rootCmd = &cobra.Command{
|
||||||
|
Use: "cobra",
|
||||||
|
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 er(msg interface{}) {
|
||||||
|
fmt.Println("Error:", msg)
|
||||||
|
os.Exit(1)
|
||||||
|
}
|
||||||
|
|
||||||
|
func initConfig() {
|
||||||
|
if cfgFile != "" {
|
||||||
|
// Use config file from the flag.
|
||||||
|
viper.SetConfigFile(cfgFile)
|
||||||
|
} else {
|
||||||
|
// Find home directory.
|
||||||
|
home, err := homedir.Dir()
|
||||||
|
if err != nil {
|
||||||
|
er(err)
|
||||||
|
}
|
||||||
|
|
||||||
|
// Search config in home directory with name ".cobra" (without extension).
|
||||||
|
viper.AddConfigPath(home)
|
||||||
|
viper.SetConfigName(".cobra")
|
||||||
|
}
|
||||||
|
|
||||||
|
viper.AutomaticEnv()
|
||||||
|
|
||||||
|
if err := viper.ReadInConfig(); err == nil {
|
||||||
|
fmt.Println("Using config file:", viper.ConfigFileUsed())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create your main.go
|
||||||
|
|
||||||
|
With the root command you need to have your main function execute it.
|
||||||
|
Execute should be run on the root for clarity, though it can be called on any command.
|
||||||
|
|
||||||
|
In a Cobra app, typically the main.go file is very bare. It serves, one purpose, to initialize Cobra.
|
||||||
|
|
||||||
|
```go
|
||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"{pathToYourApp}/cmd"
|
||||||
|
)
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
cmd.Execute()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create additional commands
|
||||||
|
|
||||||
|
Additional commands can be defined and typically are each given their own file
|
||||||
|
inside of the cmd/ directory.
|
||||||
|
|
||||||
|
If you wanted to create a version command you would create cmd/version.go and
|
||||||
|
populate it with the following:
|
||||||
|
|
||||||
|
```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")
|
||||||
|
},
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Returning and handling errors
|
||||||
|
|
||||||
|
If you wish to return an error to the caller of a command, `RunE` can be used.
|
||||||
|
|
||||||
|
```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
|
||||||
|
},
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The error can then be caught at the execute function call.
|
||||||
|
|
||||||
|
## Working with Flags
|
||||||
|
|
||||||
|
Flags provide modifiers to control how the action command operates.
|
||||||
|
|
||||||
|
### Assign flags to a command
|
||||||
|
|
||||||
|
Since the flags are defined and used in different locations, we need to
|
||||||
|
define a variable outside with the correct scope to assign the flag to
|
||||||
|
work with.
|
||||||
|
|
||||||
|
```go
|
||||||
|
var Verbose bool
|
||||||
|
var Source string
|
||||||
|
```
|
||||||
|
|
||||||
|
There are two different approaches to assign a flag.
|
||||||
|
|
||||||
|
### Persistent Flags
|
||||||
|
|
||||||
|
A flag can be 'persistent', meaning that this flag will be available to the
|
||||||
|
command it's assigned to as well as every command under that command. For
|
||||||
|
global flags, assign a flag as a persistent flag on the root.
|
||||||
|
|
||||||
|
```go
|
||||||
|
rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Local Flags
|
||||||
|
|
||||||
|
A flag can also be assigned locally, which will only apply to that specific command.
|
||||||
|
|
||||||
|
```go
|
||||||
|
localCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read from")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Local Flag on Parent Commands
|
||||||
|
|
||||||
|
By default, Cobra only parses local flags on the target command, and any local flags on
|
||||||
|
parent commands are ignored. By enabling `Command.TraverseChildren`, Cobra will
|
||||||
|
parse local flags on each command before executing the target command.
|
||||||
|
|
||||||
|
```go
|
||||||
|
command := cobra.Command{
|
||||||
|
Use: "print [OPTIONS] [COMMANDS]",
|
||||||
|
TraverseChildren: true,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Bind Flags with Config
|
||||||
|
|
||||||
|
You can also bind your flags with [viper](https://github.com/spf13/viper):
|
||||||
|
```go
|
||||||
|
var author string
|
||||||
|
|
||||||
|
func init() {
|
||||||
|
rootCmd.PersistentFlags().StringVar(&author, "author", "YOUR NAME", "Author name for copyright attribution")
|
||||||
|
viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
In this example, the persistent flag `author` is bound with `viper`.
|
||||||
|
**Note**: the variable `author` will not be set to the value from config,
|
||||||
|
when the `--author` flag is not provided by user.
|
||||||
|
|
||||||
|
More in [viper documentation](https://github.com/spf13/viper#working-with-flags).
|
||||||
|
|
||||||
|
### Required flags
|
||||||
|
|
||||||
|
Flags are optional by default. If instead you wish your command to report an error
|
||||||
|
when a flag has not been set, mark it as required:
|
||||||
|
```go
|
||||||
|
rootCmd.Flags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
|
||||||
|
rootCmd.MarkFlagRequired("region")
|
||||||
|
```
|
||||||
|
|
||||||
|
Or, for persistent flags:
|
||||||
|
```go
|
||||||
|
rootCmd.PersistentFlags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
|
||||||
|
rootCmd.MarkPersistentFlagRequired("region")
|
||||||
|
```
|
||||||
|
|
||||||
|
## Positional and Custom Arguments
|
||||||
|
|
||||||
|
Validation of positional arguments can be specified using the `Args` field
|
||||||
|
of `Command`.
|
||||||
|
|
||||||
|
The following validators are built in:
|
||||||
|
|
||||||
|
- `NoArgs` - the command will report an error if there are any positional args.
|
||||||
|
- `ArbitraryArgs` - the command will accept any args.
|
||||||
|
- `OnlyValidArgs` - the command will report an error if there are any positional args that are not in the `ValidArgs` field of `Command`.
|
||||||
|
- `MinimumNArgs(int)` - the command will report an error if there are not at least N positional args.
|
||||||
|
- `MaximumNArgs(int)` - the command will report an error if there are more than N positional args.
|
||||||
|
- `ExactArgs(int)` - the command will report an error if there are not exactly N positional args.
|
||||||
|
- `ExactValidArgs(int)` - the command will report an error if there are not exactly N positional args OR if there are any positional args that are not in the `ValidArgs` field of `Command`
|
||||||
|
- `RangeArgs(min, max)` - the command will report an error if the number of args is not between the minimum and maximum number of expected args.
|
||||||
|
|
||||||
|
An example of setting the custom validator:
|
||||||
|
|
||||||
|
```go
|
||||||
|
var cmd = &cobra.Command{
|
||||||
|
Short: "hello",
|
||||||
|
Args: func(cmd *cobra.Command, args []string) error {
|
||||||
|
if len(args) < 1 {
|
||||||
|
return errors.New("requires a color argument")
|
||||||
|
}
|
||||||
|
if myapp.IsValidColor(args[0]) {
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
return fmt.Errorf("invalid color specified: %s", args[0])
|
||||||
|
},
|
||||||
|
Run: func(cmd *cobra.Command, args []string) {
|
||||||
|
fmt.Println("Hello, World!")
|
||||||
|
},
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
In the example below, we have defined three commands. Two are at the top level
|
||||||
|
and one (cmdTimes) is a child of one of the top commands. In this case the root
|
||||||
|
is not executable, meaning that a subcommand is required. This is accomplished
|
||||||
|
by not providing a 'Run' for the 'rootCmd'.
|
||||||
|
|
||||||
|
We have only defined one flag for a single command.
|
||||||
|
|
||||||
|
More documentation about flags is available at https://github.com/spf13/pflag
|
||||||
|
|
||||||
|
```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()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For a more complete example of a larger application, please checkout [Hugo](http://gohugo.io/).
|
||||||
|
|
||||||
|
## Help Command
|
||||||
|
|
||||||
|
Cobra automatically adds a help command to your application when you have subcommands.
|
||||||
|
This will be called when a user runs 'app help'. Additionally, help will also
|
||||||
|
support all other commands as input. Say, for instance, you have a command called
|
||||||
|
'create' without any additional configuration; Cobra will work when 'app help
|
||||||
|
create' is called. Every command will automatically have the '--help' flag added.
|
||||||
|
|
||||||
|
### Example
|
||||||
|
|
||||||
|
The following output is automatically generated by Cobra. Nothing beyond the
|
||||||
|
command and flag definitions are needed.
|
||||||
|
|
||||||
|
$ cobra 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 [command]
|
||||||
|
|
||||||
|
Available Commands:
|
||||||
|
add Add a command to a Cobra Application
|
||||||
|
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
|
||||||
|
-l, --license string name of license for the project
|
||||||
|
--viper use Viper for configuration (default true)
|
||||||
|
|
||||||
|
Use "cobra [command] --help" for more information about a command.
|
||||||
|
|
||||||
|
|
||||||
|
Help is just a command like any other. There is no special logic or behavior
|
||||||
|
around it. In fact, you can provide your own if you want.
|
||||||
|
|
||||||
|
### Defining your own help
|
||||||
|
|
||||||
|
You can provide your own Help command or your own template for the default command to use
|
||||||
|
with following functions:
|
||||||
|
|
||||||
|
```go
|
||||||
|
cmd.SetHelpCommand(cmd *Command)
|
||||||
|
cmd.SetHelpFunc(f func(*Command, []string))
|
||||||
|
cmd.SetHelpTemplate(s string)
|
||||||
|
```
|
||||||
|
|
||||||
|
The latter two will also apply to any children commands.
|
||||||
|
|
||||||
|
## Usage Message
|
||||||
|
|
||||||
|
When the user provides an invalid flag or invalid command, Cobra responds by
|
||||||
|
showing the user the 'usage'.
|
||||||
|
|
||||||
|
### Example
|
||||||
|
You may recognize this from the help above. That's because the default help
|
||||||
|
embeds the usage as part of its output.
|
||||||
|
|
||||||
|
$ cobra --invalid
|
||||||
|
Error: unknown flag: --invalid
|
||||||
|
Usage:
|
||||||
|
cobra [command]
|
||||||
|
|
||||||
|
Available Commands:
|
||||||
|
add Add a command to a Cobra Application
|
||||||
|
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
|
||||||
|
-l, --license string name of license for the project
|
||||||
|
--viper use Viper for configuration (default true)
|
||||||
|
|
||||||
|
Use "cobra [command] --help" for more information about a command.
|
||||||
|
|
||||||
|
### Defining your own usage
|
||||||
|
You can provide your own usage function or template for Cobra to use.
|
||||||
|
Like help, the function and template are overridable through public methods:
|
||||||
|
|
||||||
|
```go
|
||||||
|
cmd.SetUsageFunc(f func(*Command) error)
|
||||||
|
cmd.SetUsageTemplate(s string)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Version Flag
|
||||||
|
|
||||||
|
Cobra adds a top-level '--version' flag if the Version field is set on the root command.
|
||||||
|
Running an application with the '--version' flag will print the version to stdout using
|
||||||
|
the version template. The template can be customized using the
|
||||||
|
`cmd.SetVersionTemplate(s string)` function.
|
||||||
|
|
||||||
|
## PreRun and PostRun Hooks
|
||||||
|
|
||||||
|
It is possible to run functions before or after the main `Run` function of your command. The `PersistentPreRun` and `PreRun` functions will be executed before `Run`. `PersistentPostRun` and `PostRun` will be executed after `Run`. The `Persistent*Run` functions will be inherited by children if they do not declare their own. These functions are run in the following order:
|
||||||
|
|
||||||
|
- `PersistentPreRun`
|
||||||
|
- `PreRun`
|
||||||
|
- `Run`
|
||||||
|
- `PostRun`
|
||||||
|
- `PersistentPostRun`
|
||||||
|
|
||||||
|
An example of two commands which use all of these features is below. When the subcommand is executed, it will run the root command's `PersistentPreRun` but not the root command's `PersistentPostRun`:
|
||||||
|
|
||||||
|
```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()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Output:
|
||||||
|
```
|
||||||
|
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]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Suggestions when "unknown command" happens
|
||||||
|
|
||||||
|
Cobra will print automatic suggestions when "unknown command" errors happen. This allows Cobra to behave similarly to the `git` command when a typo happens. For example:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ hugo srever
|
||||||
|
Error: unknown command "srever" for "hugo"
|
||||||
|
|
||||||
|
Did you mean this?
|
||||||
|
server
|
||||||
|
|
||||||
|
Run 'hugo --help' for usage.
|
||||||
|
```
|
||||||
|
|
||||||
|
Suggestions are automatic based on every subcommand registered and use an implementation of [Levenshtein distance](http://en.wikipedia.org/wiki/Levenshtein_distance). Every registered command that matches a minimum distance of 2 (ignoring case) will be displayed as a suggestion.
|
||||||
|
|
||||||
|
If you need to disable suggestions or tweak the string distance in your command, use:
|
||||||
|
|
||||||
|
```go
|
||||||
|
command.DisableSuggestions = true
|
||||||
|
```
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
```go
|
||||||
|
command.SuggestionsMinimumDistance = 1
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also explicitly set names for which a given command will be suggested using the `SuggestFor` attribute. This allows suggestions for strings that are not close in terms of string distance, but makes sense in your set of commands and for some which you don't want aliases. Example:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ kubectl remove
|
||||||
|
Error: unknown command "remove" for "kubectl"
|
||||||
|
|
||||||
|
Did you mean this?
|
||||||
|
delete
|
||||||
|
|
||||||
|
Run 'kubectl help' for usage.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Generating documentation for your command
|
||||||
|
|
||||||
|
Cobra can generate documentation based on subcommands, flags, etc. Read more about it in the [docs generation documentation](doc/README.md).
|
||||||
|
|
||||||
|
## Generating shell completions
|
||||||
|
|
||||||
|
Cobra can generate a shell-completion file for the following shells: Bash, Zsh, Fish, Powershell. If you add more information to your commands, these completions can be amazingly powerful and flexible. Read more about it in [Shell Completions](shell_completions.md).
|
||||||
17
site/content/installing.md
Normal file
17
site/content/installing.md
Normal file
|
|
@ -0,0 +1,17 @@
|
||||||
|
---
|
||||||
|
weight: 3
|
||||||
|
---
|
||||||
|
|
||||||
|
# Installing
|
||||||
|
|
||||||
|
Using Cobra is easy. First, use `go get` to install the latest version
|
||||||
|
of the library. This command will install the `cobra` generator executable
|
||||||
|
along with the library and its dependencies:
|
||||||
|
|
||||||
|
go get -u github.com/spf13/cobra
|
||||||
|
|
||||||
|
Next, include Cobra in your application:
|
||||||
|
|
||||||
|
```go
|
||||||
|
import "github.com/spf13/cobra"
|
||||||
|
```
|
||||||
7
site/content/license.md
Normal file
7
site/content/license.md
Normal file
|
|
@ -0,0 +1,7 @@
|
||||||
|
---
|
||||||
|
weight: 33
|
||||||
|
---
|
||||||
|
|
||||||
|
# License
|
||||||
|
|
||||||
|
Cobra is released under the Apache 2.0 license. See [LICENSE.txt](https://github.com/spf13/cobra/blob/master/LICENSE.txt)
|
||||||
27
site/content/overview.md
Normal file
27
site/content/overview.md
Normal file
|
|
@ -0,0 +1,27 @@
|
||||||
|
---
|
||||||
|
weight: 1
|
||||||
|
---
|
||||||
|
|
||||||
|
# Overview
|
||||||
|
|
||||||
|
Cobra is a library providing a simple interface to create powerful modern CLI
|
||||||
|
interfaces similar to git & go tools.
|
||||||
|
|
||||||
|
Cobra is also an application that will generate your application scaffolding to rapidly
|
||||||
|
develop a Cobra-based application.
|
||||||
|
|
||||||
|
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
|
||||||
|
* Easy generation of applications & commands with `cobra init appname` & `cobra add cmdname`
|
||||||
|
* Intelligent suggestions (`app srver`... did you mean `app server`?)
|
||||||
|
* Automatic help generation for commands and flags
|
||||||
|
* 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 tight integration with [viper](http://github.com/spf13/viper) for 12-factor apps
|
||||||
|
|
@ -1,3 +1,7 @@
|
||||||
|
---
|
||||||
|
weight: 32
|
||||||
|
---
|
||||||
|
|
||||||
# Projects using Cobra
|
# Projects using Cobra
|
||||||
|
|
||||||
- [Allero](https://github.com/allero-io/allero)
|
- [Allero](https://github.com/allero-io/allero)
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue