README.md
1
2
3Cobra is both a library for creating powerful modern CLI applications as well as a program to generate applications and command files.
4
5Cobra 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
7name a few. [This list](./projects_using_cobra.md) contains a more extensive list of projects using Cobra.
8
9[](https://github.com/spf13/cobra/actions?query=workflow%3ATest)
10[](https://godoc.org/github.com/spf13/cobra)
11[](https://goreportcard.com/report/github.com/spf13/cobra)
12[](https://gophers.slack.com/archives/CD3LP1199)
13
14# Table of Contents
15
16- [Overview](#overview)
17- [Concepts](#concepts)
18 * [Commands](#commands)
19 * [Flags](#flags)
20- [Installing](#installing)
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)
34- [License](#license)
35
36# Overview
37
38Cobra is a library providing a simple interface to create powerful modern CLI
39interfaces similar to git & go tools.
40
41Cobra is also an application that will generate your application scaffolding to rapidly
42develop a Cobra-based application.
43
44Cobra provides:
45* Easy subcommand-based CLIs: `app server`, `app fetch`, etc.
46* Fully POSIX-compliant flags (including short & long versions)
47* Nested subcommands
48* Global, local and cascading flags
49* Easy generation of applications & commands with `cobra init appname` & `cobra add cmdname`
50* Intelligent suggestions (`app srver`... did you mean `app server`?)
51* Automatic help generation for commands and flags
52* Automatic help flag recognition of `-h`, `--help`, etc.
53* Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell)
54* Automatically generated man pages for your application
55* Command aliases so you can change things without breaking them
56* The flexibility to define your own help, usage, etc.
57* Optional tight integration with [viper](http://github.com/spf13/viper) for 12-factor apps
58
59# Concepts
60
61Cobra is built on a structure of commands, arguments & flags.
62
63**Commands** represent actions, **Args** are things and **Flags** are modifiers for those actions.
64
65The best applications read like sentences when used, and as a result, users
66intuitively know how to interact with them.
67
68The pattern to follow is
69`APPNAME VERB NOUN --ADJECTIVE.`
70 or
71`APPNAME COMMAND ARG --FLAG`
72
73A few good real world examples may better illustrate this point.
74
75In the following example, 'server' is a command, and 'port' is a flag:
76
77 hugo server --port=1313
78
79In this command we are telling Git to clone the url bare.
80
81 git clone URL --bare
82
83## Commands
84
85Command is the central point of the application. Each interaction that
86the application supports will be contained in a Command. A command can
87have children commands and optionally run an action.
88
89In the example above, 'server' is the command.
90
91[More about cobra.Command](https://godoc.org/github.com/spf13/cobra#Command)
92
93## Flags
94
95A flag is a way to modify the behavior of a command. Cobra supports
96fully POSIX-compliant flags as well as the Go [flag package](https://golang.org/pkg/flag/).
97A Cobra command can define flags that persist through to children commands
98and flags that are only available to that command.
99
100In the example above, 'port' is the flag.
101
102Flag functionality is provided by the [pflag
103library](https://github.com/spf13/pflag), a fork of the flag standard library
104which maintains the same interface while adding POSIX compliance.
105
106# Installing
107Using Cobra is easy. First, use `go get` to install the latest version
108of the library. This command will install the `cobra` generator executable
109along with the library and its dependencies:
110
111 go get -u github.com/spf13/cobra
112
113Next, include Cobra in your application:
114
115```go
116import "github.com/spf13/cobra"
117```
118
119# Usage
120
121See [User Guide](user_guide.md).
122
123# License
124
125Cobra is released under the Apache 2.0 license. See [LICENSE.txt](https://github.com/spf13/cobra/blob/master/LICENSE.txt)
126
){kind=link}
){kind=link}