Go to file
Steve Francia dcf42b25f7 Change generator to require opting in to viper.
Cobra and Viper are great together, but it's not uncommon to use them apart.
New Cobra users don't know better and including Viper by default adds complexity to the skeleton.
2021-11-03 15:36:51 -04:00
.github ci: test golang 1.16.x and 1.17.x too (#1425) 2021-08-25 21:18:53 -06:00
cobra Change generator to require opting in to viper. 2021-11-03 15:36:51 -04:00
doc go.mod: cpuguy83/go-md2man/v2 v2.0.1 (#1460) 2021-08-05 11:08:25 -06:00
.gitignore leverage makefile to run build tasks (#976) 2020-02-20 12:25:38 -07:00
.golangci.yml Use golangci-lint (#1044) 2021-02-07 17:08:50 -07:00
.mailmap Add .mailcap for a more tidy "git shortlog" output 2015-11-20 15:24:23 -07:00
args_test.go Added ExactValidArgs (#765) 2018-10-21 10:01:21 -04:00
args.go Fish completion using Go completion (#1048) 2020-04-10 13:56:28 -06:00
bash_completions_test.go Use golangci-lint (#1044) 2021-02-07 17:08:50 -07:00
bash_completions.go DisableFlagParsing must disable flag completion (#1161) 2021-11-01 13:01:33 -06:00
bash_completions.md Bash completion V2 with completion descriptions (#1146) 2021-06-30 15:24:58 -06:00
bash_completionsV2.go Bash completion V2 with completion descriptions (#1146) 2021-06-30 15:24:58 -06:00
CHANGELOG.md Fix typo 2021-02-10 12:40:59 -07:00
cobra_test.go Use golangci-lint (#1044) 2021-02-07 17:08:50 -07:00
cobra.go Use golangci-lint (#1044) 2021-02-07 17:08:50 -07:00
command_notwin.go ci: test golang 1.16.x and 1.17.x too (#1425) 2021-08-25 21:18:53 -06:00
command_test.go Pass context to completion (#1265) 2021-05-03 10:33:57 -06:00
command_win.go ci: test golang 1.16.x and 1.17.x too (#1425) 2021-08-25 21:18:53 -06:00
command.go Fix flag completion (#1438) 2021-07-02 09:25:47 -06:00
completions_test.go DisableFlagParsing must disable flag completion (#1161) 2021-11-01 13:01:33 -06:00
completions.go DisableFlagParsing must disable flag completion (#1161) 2021-11-01 13:01:33 -06:00
CONDUCT.md Cobra User Contract (#1292) 2021-01-26 10:55:24 -07:00
CONTRIBUTING.md Add CONTRIBUTING.md (#1183) 2020-08-10 22:14:21 -06:00
fish_completions_test.go Use golangci-lint (#1044) 2021-02-07 17:08:50 -07:00
fish_completions.go Fix flag completion (#1438) 2021-07-02 09:25:47 -06:00
fish_completions.md Extend Go completions and revamp zsh comp (#1070) (#1070) 2020-06-29 13:52:14 -06:00
go.mod ci: test golang 1.16.x and 1.17.x too (#1425) 2021-08-25 21:18:53 -06:00
go.sum go.mod: cpuguy83/go-md2man/v2 v2.0.1 (#1460) 2021-08-05 11:08:25 -06:00
LICENSE.txt adding license 2013-09-03 18:46:13 -04:00
Makefile Use golangci-lint (#1044) 2021-02-07 17:08:50 -07:00
powershell_completions.go Correcting misspelled words (#1349) 2021-05-10 17:19:33 -06:00
powershell_completions.md powershell completion with custom comp (#1208) 2020-12-29 07:57:32 -07:00
projects_using_cobra.md Update projects-using markdown with Tanzu (#1501) 2021-10-04 14:58:08 -06:00
README.md readme: remove ToC, since it's now shown by GitHub (#1429) 2021-11-02 09:10:14 -06:00
shell_completions.go Extend Go completions and revamp zsh comp (#1070) (#1070) 2020-06-29 13:52:14 -06:00
shell_completions.md Fix documentation (#1434) 2021-07-01 09:49:30 -06:00
user_guide.md drop mitchellh/go-homedir (#853) 2021-06-30 14:08:43 -04:00
zsh_completions.go Fix zsh for DirectiveNoSpace and DirectiveNoFileComp (#1213) 2021-05-03 10:54:00 -06:00
zsh_completions.md Improve zsh completion documentation (#1169) 2020-07-19 16:02:46 -06:00

cobra logo

Cobra is both a library for creating powerful modern CLI applications as well as a program to generate applications and command files.

Cobra is used in many Go projects such as Kubernetes, Hugo, and Github CLI to name a few. This list contains a more extensive list of projects using Cobra.

GoDoc Go Report Card Slack

Overview

Cobra is a library providing a simple interface to create powerful modern CLI interfaces similar to git & go tools.

Cobra is also an application that will generate your application scaffolding to rapidly develop a Cobra-based application.

Cobra provides:

  • Easy subcommand-based CLIs: app server, app fetch, etc.
  • Fully POSIX-compliant flags (including short & long versions)
  • Nested subcommands
  • Global, local and cascading flags
  • Easy generation of applications & commands with cobra init appname & cobra add cmdname
  • Intelligent suggestions (app srver... did you mean app server?)
  • Automatic help generation for commands and flags
  • Automatic help flag recognition of -h, --help, etc.
  • Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell)
  • Automatically generated man pages for your application
  • Command aliases so you can change things without breaking them
  • The flexibility to define your own help, usage, etc.
  • Optional tight integration with viper for 12-factor apps

Concepts

Cobra is built on a structure of commands, arguments & flags.

Commands represent actions, Args are things and Flags are modifiers for those actions.

The best applications read like sentences when used, and as a result, users intuitively know how to interact with them.

The pattern to follow is APPNAME VERB NOUN --ADJECTIVE. or APPNAME COMMAND ARG --FLAG

A few good real world examples may better illustrate this point.

In the following example, 'server' is a command, and 'port' is a flag:

hugo server --port=1313

In this command we are telling Git to clone the url bare.

git clone URL --bare

Commands

Command is the central point of the application. Each interaction that the application supports will be contained in a Command. A command can have children commands and optionally run an action.

In the example above, 'server' is the command.

More about cobra.Command

Flags

A flag is a way to modify the behavior of a command. Cobra supports fully POSIX-compliant flags as well as the Go flag package. A Cobra command can define flags that persist through to children commands and flags that are only available to that command.

In the example above, 'port' is the flag.

Flag functionality is provided by the pflag library, a fork of the flag standard library which maintains the same interface while adding POSIX compliance.

Installing

Using Cobra is easy. First, use go get to install the latest version of the library. This command will install the cobra generator executable along with the library and its dependencies:

go get -u github.com/spf13/cobra

Next, include Cobra in your application:

import "github.com/spf13/cobra"

Usage

See User Guide.

License

Cobra is released under the Apache 2.0 license. See LICENSE.txt