git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/cobra/README.md (about)

     1  ![cobra logo](https://cloud.githubusercontent.com/assets/173412/10886352/ad566232-814f-11e5-9cd0-aa101788c117.png)
     2  
     3  Cobra is a library for creating powerful modern CLI applications.
     4  
     5  Cobra is used in many Go projects such as [Kubernetes](https://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.
     8  
     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)
    10  [![Go Reference](https://pkg.go.dev/badge/github.com/spf13/cobra.svg)](https://pkg.go.dev/github.com/spf13/cobra)
    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)
    13  
    14  # Overview
    15  
    16  Cobra is a library providing a simple interface to create powerful modern CLI
    17  interfaces similar to git & go tools.
    18  
    19  Cobra provides:
    20  * Easy subcommand-based CLIs: `app server`, `app fetch`, etc.
    21  * Fully POSIX-compliant flags (including short & long versions)
    22  * Nested subcommands
    23  * Global, local and cascading flags
    24  * Intelligent suggestions (`app srver`... did you mean `app server`?)
    25  * Automatic help generation for commands and flags
    26  * Automatic help flag recognition of `-h`, `--help`, etc.
    27  * Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell)
    28  * Automatically generated man pages for your application
    29  * Command aliases so you can change things without breaking them
    30  * The flexibility to define your own help, usage, etc.
    31  * Optional seamless integration with [viper](https://github.com/spf13/viper) for 12-factor apps
    32  
    33  # Concepts
    34  
    35  Cobra is built on a structure of commands, arguments & flags.
    36  
    37  **Commands** represent actions, **Args** are things and **Flags** are modifiers for those actions.
    38  
    39  The best applications read like sentences when used, and as a result, users
    40  intuitively know how to interact with them.
    41  
    42  The pattern to follow is
    43  `APPNAME VERB NOUN --ADJECTIVE`
    44      or
    45  `APPNAME COMMAND ARG --FLAG`.
    46  
    47  A few good real world examples may better illustrate this point.
    48  
    49  In the following example, 'server' is a command, and 'port' is a flag:
    50  
    51      hugo server --port=1313
    52  
    53  In this command we are telling Git to clone the url bare.
    54  
    55      git clone URL --bare
    56  
    57  ## Commands
    58  
    59  Command is the central point of the application. Each interaction that
    60  the application supports will be contained in a Command. A command can
    61  have children commands and optionally run an action.
    62  
    63  In the example above, 'server' is the command.
    64  
    65  [More about cobra.Command](https://pkg.go.dev/github.com/spf13/cobra#Command)
    66  
    67  ## Flags
    68  
    69  A flag is a way to modify the behavior of a command. Cobra supports
    70  fully POSIX-compliant flags as well as the Go [flag package](https://golang.org/pkg/flag/).
    71  A Cobra command can define flags that persist through to children commands
    72  and flags that are only available to that command.
    73  
    74  In the example above, 'port' is the flag.
    75  
    76  Flag functionality is provided by the [pflag
    77  library](https://github.com/spf13/pflag), a fork of the flag standard library
    78  which maintains the same interface while adding POSIX compliance.
    79  
    80  # Installing
    81  Using Cobra is easy. First, use `go get` to install the latest version
    82  of the library.     
    83  
    84  ```
    85  go get -u github.com/spf13/cobra@latest
    86  ```
    87  
    88  Next, include Cobra in your application:
    89  
    90  ```go
    91  import "github.com/spf13/cobra"
    92  ```
    93  
    94  # Usage
    95  `cobra-cli` is a command line program to generate cobra applications and command files.
    96  It will bootstrap your application scaffolding to rapidly
    97  develop a Cobra-based application. It is the easiest way to incorporate Cobra into your application.
    98  
    99  It can be installed by running:
   100  
   101  ```
   102  go install github.com/spf13/cobra-cli@latest
   103  ```
   104  
   105  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)
   106  
   107  For complete details on using the Cobra library, please read the [The Cobra User Guide](user_guide.md).
   108  
   109  # License
   110  
   111  Cobra is released under the Apache 2.0 license. See [LICENSE.txt](https://github.com/spf13/cobra/blob/master/LICENSE.txt)