README.md

Documentation: github.com/spf13/cobra

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