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