cobra/README.md

126 lines
5.0 KiB
Markdown
Raw Normal View History

2015-11-02 15:53:04 +00:00
![cobra logo](https://cloud.githubusercontent.com/assets/173412/10886352/ad566232-814f-11e5-9cd0-aa101788c117.png)
2013-09-03 22:45:49 +00:00
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](http://kubernetes.io/),
[Hugo](https://gohugo.io), and [Github CLI](https://github.com/cli/cli) to
name a few. [This list](./projects_using_cobra.md) contains a more extensive list of projects using Cobra.
2013-09-03 22:45:49 +00:00
[![](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)
[![GoDoc](https://godoc.org/github.com/spf13/cobra?status.svg)](https://godoc.org/github.com/spf13/cobra)
2019-10-03 21:53:10 +00:00
[![Go Report Card](https://goreportcard.com/badge/github.com/spf13/cobra)](https://goreportcard.com/report/github.com/spf13/cobra)
[![Slack](https://img.shields.io/badge/Slack-cobra-brightgreen)](https://gophers.slack.com/archives/CD3LP1199)
2013-09-24 21:08:47 +00:00
2017-10-02 09:32:00 +00:00
# Table of Contents
- [Overview](#overview)
- [Concepts](#concepts)
* [Commands](#commands)
* [Flags](#flags)
- [Installing](#installing)
- [Usage](#usage)
* [Using the Cobra Generator](user_guide.md#using-the-cobra-generator)
* [Using the Cobra Library](user_guide.md#using-the-cobra-library)
* [Working with Flags](user_guide.md#working-with-flags)
* [Positional and Custom Arguments](user_guide.md#positional-and-custom-arguments)
* [Example](user_guide.md#example)
* [Help Command](user_guide.md#help-command)
* [Usage Message](user_guide.md#usage-message)
* [PreRun and PostRun Hooks](user_guide.md#prerun-and-postrun-hooks)
* [Suggestions when "unknown command" happens](user_guide.md#suggestions-when-unknown-command-happens)
* [Generating documentation for your command](user_guide.md#generating-documentation-for-your-command)
* [Generating shell completions](user_guide.md#generating-shell-completions)
2020-08-11 04:14:21 +00:00
- [Contributing](CONTRIBUTING.md)
2017-10-02 09:32:00 +00:00
- [License](#license)
2015-11-02 15:55:33 +00:00
2015-11-19 03:56:25 +00:00
# Overview
2013-09-03 22:45:49 +00:00
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
2015-11-15 05:46:43 +00:00
develop a Cobra-based application.
2013-09-03 22:45:49 +00:00
Cobra provides:
2015-11-15 05:46:43 +00:00
* 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`
2015-11-15 05:46:43 +00:00
* 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
2017-05-01 14:51:43 +00:00
* The flexibility to define your own help, usage, etc.
2015-11-15 05:46:43 +00:00
* Optional tight integration with [viper](http://github.com/spf13/viper) for 12-factor apps
2013-09-03 22:45:49 +00:00
2015-11-19 03:56:25 +00:00
# Concepts
2013-09-03 22:45:49 +00:00
2015-11-19 03:56:25 +00:00
Cobra is built on a structure of commands, arguments & flags.
2013-09-03 22:45:49 +00:00
2015-11-19 03:56:25 +00:00
**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.
2015-11-19 03:56:25 +00:00
The pattern to follow is
2015-11-19 03:56:25 +00:00
`APPNAME VERB NOUN --ADJECTIVE.`
or
`APPNAME COMMAND ARG --FLAG`
A few good real world examples may better illustrate this point.
2013-09-03 22:45:49 +00:00
2015-11-15 05:46:43 +00:00
In the following example, 'server' is a command, and 'port' is a flag:
2013-09-03 22:45:49 +00:00
2017-04-29 10:02:02 +00:00
hugo server --port=1313
2015-11-19 03:56:25 +00:00
In this command we are telling Git to clone the url bare.
2013-09-03 22:45:49 +00:00
2017-04-29 10:02:02 +00:00
git clone URL --bare
2015-11-19 03:56:25 +00:00
## Commands
2013-09-03 22:45:49 +00:00
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.
2015-11-15 05:46:43 +00:00
In the example above, 'server' is the command.
2013-09-03 22:45:49 +00:00
2017-10-02 09:32:00 +00:00
[More about cobra.Command](https://godoc.org/github.com/spf13/cobra#Command)
2013-09-03 22:45:49 +00:00
2015-11-19 03:56:25 +00:00
## Flags
2013-09-03 22:45:49 +00:00
2017-10-02 09:32:00 +00:00
A flag is a way to modify the behavior of a command. Cobra supports
2015-11-15 05:46:43 +00:00
fully POSIX-compliant flags as well as the Go [flag package](https://golang.org/pkg/flag/).
2014-01-12 05:34:06 +00:00
A Cobra command can define flags that persist through to children commands
2013-11-05 17:40:10 +00:00
and flags that are only available to that command.
2013-09-03 22:45:49 +00:00
2015-11-15 05:46:43 +00:00
In the example above, 'port' is the flag.
2013-09-03 22:45:49 +00:00
2013-11-05 17:40:10 +00:00
Flag functionality is provided by the [pflag
library](https://github.com/spf13/pflag), a fork of the flag standard library
2015-11-15 05:46:43 +00:00
which maintains the same interface while adding POSIX compliance.
2013-11-05 17:40:10 +00:00
2015-11-19 03:56:25 +00:00
# Installing
2015-11-15 05:46:43 +00:00
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:
2013-09-03 22:45:49 +00:00
go get -u github.com/spf13/cobra
2013-09-03 22:45:49 +00:00
2015-11-15 05:46:43 +00:00
Next, include Cobra in your application:
2013-09-03 22:45:49 +00:00
2015-11-15 05:46:43 +00:00
```go
import "github.com/spf13/cobra"
```
2013-09-03 22:45:49 +00:00
# Usage
2015-11-19 03:56:25 +00:00
See [User Guide](user_guide.md).
2017-10-02 09:32:00 +00:00
# License
2013-09-03 22:45:49 +00:00
2014-05-05 00:01:50 +00:00
Cobra is released under the Apache 2.0 license. See [LICENSE.txt](https://github.com/spf13/cobra/blob/master/LICENSE.txt)