author | Mikael Berthe <mikael@lilotux.net> |
Sun, 11 Jul 2021 10:35:56 +0200 | |
changeset 256 | 6d9efbef00a9 |
parent 251 | 1c52a0eeb952 |
child 260 | 445e01aede7e |
permissions | -rw-r--r-- |
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
1 |
![cobra logo](https://cloud.githubusercontent.com/assets/173412/10886352/ad566232-814f-11e5-9cd0-aa101788c117.png) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
2 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
3 |
Cobra is both a library for creating powerful modern CLI applications as well as a program to generate applications and command files. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
4 |
|
256 | 5 |
Cobra is used in many Go projects such as [Kubernetes](http://kubernetes.io/), |
6 |
[Hugo](https://gohugo.io), and [Github CLI](https://github.com/cli/cli) to |
|
7 |
name a few. [This list](./projects_using_cobra.md) contains a more extensive list of projects using Cobra. |
|
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
8 |
|
256 | 9 |
[![](https://img.shields.io/github/workflow/status/spf13/cobra/Test?longCache=tru&label=Test&logo=github%20actions&logoColor=fff)](https://github.com/spf13/cobra/actions?query=workflow%3ATest) |
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
10 |
[![GoDoc](https://godoc.org/github.com/spf13/cobra?status.svg)](https://godoc.org/github.com/spf13/cobra) |
256 | 11 |
[![Go Report Card](https://goreportcard.com/badge/github.com/spf13/cobra)](https://goreportcard.com/report/github.com/spf13/cobra) |
12 |
[![Slack](https://img.shields.io/badge/Slack-cobra-brightgreen)](https://gophers.slack.com/archives/CD3LP1199) |
|
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
13 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
14 |
# Table of Contents |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
15 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
16 |
- [Overview](#overview) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
17 |
- [Concepts](#concepts) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
18 |
* [Commands](#commands) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
19 |
* [Flags](#flags) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
20 |
- [Installing](#installing) |
256 | 21 |
- [Usage](#usage) |
22 |
* [Using the Cobra Generator](user_guide.md#using-the-cobra-generator) |
|
23 |
* [Using the Cobra Library](user_guide.md#using-the-cobra-library) |
|
24 |
* [Working with Flags](user_guide.md#working-with-flags) |
|
25 |
* [Positional and Custom Arguments](user_guide.md#positional-and-custom-arguments) |
|
26 |
* [Example](user_guide.md#example) |
|
27 |
* [Help Command](user_guide.md#help-command) |
|
28 |
* [Usage Message](user_guide.md#usage-message) |
|
29 |
* [PreRun and PostRun Hooks](user_guide.md#prerun-and-postrun-hooks) |
|
30 |
* [Suggestions when "unknown command" happens](user_guide.md#suggestions-when-unknown-command-happens) |
|
31 |
* [Generating documentation for your command](user_guide.md#generating-documentation-for-your-command) |
|
32 |
* [Generating shell completions](user_guide.md#generating-shell-completions) |
|
33 |
- [Contributing](CONTRIBUTING.md) |
|
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
34 |
- [License](#license) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
35 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
36 |
# Overview |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
37 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
38 |
Cobra is a library providing a simple interface to create powerful modern CLI |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
39 |
interfaces similar to git & go tools. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
40 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
41 |
Cobra is also an application that will generate your application scaffolding to rapidly |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
42 |
develop a Cobra-based application. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
43 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
44 |
Cobra provides: |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
45 |
* Easy subcommand-based CLIs: `app server`, `app fetch`, etc. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
46 |
* Fully POSIX-compliant flags (including short & long versions) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
47 |
* Nested subcommands |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
48 |
* Global, local and cascading flags |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
49 |
* Easy generation of applications & commands with `cobra init appname` & `cobra add cmdname` |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
50 |
* Intelligent suggestions (`app srver`... did you mean `app server`?) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
51 |
* Automatic help generation for commands and flags |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
52 |
* Automatic help flag recognition of `-h`, `--help`, etc. |
256 | 53 |
* Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell) |
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
54 |
* Automatically generated man pages for your application |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
55 |
* Command aliases so you can change things without breaking them |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
56 |
* The flexibility to define your own help, usage, etc. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
57 |
* Optional tight integration with [viper](http://github.com/spf13/viper) for 12-factor apps |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
58 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
59 |
# Concepts |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
60 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
61 |
Cobra is built on a structure of commands, arguments & flags. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
62 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
63 |
**Commands** represent actions, **Args** are things and **Flags** are modifiers for those actions. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
64 |
|
256 | 65 |
The best applications read like sentences when used, and as a result, users |
66 |
intuitively know how to interact with them. |
|
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
67 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
68 |
The pattern to follow is |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
69 |
`APPNAME VERB NOUN --ADJECTIVE.` |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
70 |
or |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
71 |
`APPNAME COMMAND ARG --FLAG` |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
72 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
73 |
A few good real world examples may better illustrate this point. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
74 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
75 |
In the following example, 'server' is a command, and 'port' is a flag: |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
76 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
77 |
hugo server --port=1313 |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
78 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
79 |
In this command we are telling Git to clone the url bare. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
80 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
81 |
git clone URL --bare |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
82 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
83 |
## Commands |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
84 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
85 |
Command is the central point of the application. Each interaction that |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
86 |
the application supports will be contained in a Command. A command can |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
87 |
have children commands and optionally run an action. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
88 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
89 |
In the example above, 'server' is the command. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
90 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
91 |
[More about cobra.Command](https://godoc.org/github.com/spf13/cobra#Command) |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
92 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
93 |
## Flags |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
94 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
95 |
A flag is a way to modify the behavior of a command. Cobra supports |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
96 |
fully POSIX-compliant flags as well as the Go [flag package](https://golang.org/pkg/flag/). |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
97 |
A Cobra command can define flags that persist through to children commands |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
98 |
and flags that are only available to that command. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
99 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
100 |
In the example above, 'port' is the flag. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
101 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
102 |
Flag functionality is provided by the [pflag |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
103 |
library](https://github.com/spf13/pflag), a fork of the flag standard library |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
104 |
which maintains the same interface while adding POSIX compliance. |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
105 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
106 |
# Installing |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
107 |
Using Cobra is easy. First, use `go get` to install the latest version |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
108 |
of the library. This command will install the `cobra` generator executable |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
109 |
along with the library and its dependencies: |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
110 |
|
256 | 111 |
go get -u github.com/spf13/cobra |
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
112 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
113 |
Next, include Cobra in your application: |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
114 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
115 |
```go |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
116 |
import "github.com/spf13/cobra" |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
117 |
``` |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
118 |
|
256 | 119 |
# Usage |
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
120 |
|
256 | 121 |
See [User Guide](user_guide.md). |
242
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
122 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
123 |
# License |
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
124 |
|
2a9ec03fe5a1
Use vendoring for backward compatibility
Mikael Berthe <mikael@lilotux.net>
parents:
diff
changeset
|
125 |
Cobra is released under the Apache 2.0 license. See [LICENSE.txt](https://github.com/spf13/cobra/blob/master/LICENSE.txt) |