vendor/github.com/spf13/cobra/cobra/README.md

   1 # Cobra Generator
   2
   3 Cobra provides its own program that will create your application and add any
   4 commands you want. It's the easiest way to incorporate Cobra into your application.
   5
   6 In order to use the cobra command, compile it using the following command:
   7
   8     go get github.com/spf13/cobra/cobra
   9
  10 This will create the cobra executable under your `$GOPATH/bin` directory.
  11
  12 ### cobra init
  13
  14 The `cobra init [app]` command will create your initial application code
  15 for you. It is a very powerful application that will populate your program with
  16 the right structure so you can immediately enjoy all the benefits of Cobra. It
  17 will also automatically apply the license you specify to your application.
  18
  19 Cobra init is pretty smart. You can provide it a full path, or simply a path
  20 similar to what is expected in the import.
  21
  22 ```
  23 cobra init github.com/spf13/newApp
  24 ```
  25
  26 ### cobra add
  27
  28 Once an application is initialized, Cobra can create additional commands for you.
  29 Let's say you created an app and you wanted the following commands for it:
  30
  31 * app serve
  32 * app config
  33 * app config create
  34
  35 In your project directory (where your main.go file is) you would run the following:
  36
  37 ```
  38 cobra add serve
  39 cobra add config
  40 cobra add create -p 'configCmd'
  41 ```
  42
  43 *Note: Use camelCase (not snake_case/snake-case) for command names.
  44 Otherwise, you will encounter errors.
  45 For example, `cobra add add-user` is incorrect, but `cobra add addUser` is valid.*
  46
  47 Once you have run these three commands you would have an app structure similar to
  48 the following:
  49
  50 ```
  51   ▾ app/
  52     ▾ cmd/
  53         serve.go
  54         config.go
  55         create.go
  56       main.go
  57 ```
  58
  59 At this point you can run `go run main.go` and it would run your app. `go run
  60 main.go serve`, `go run main.go config`, `go run main.go config create` along
  61 with `go run main.go help serve`, etc. would all work.
  62
  63 Obviously you haven't added your own code to these yet. The commands are ready
  64 for you to give them their tasks. Have fun!
  65
  66 ### Configuring the cobra generator
  67
  68 The Cobra generator will be easier to use if you provide a simple configuration
  69 file which will help you eliminate providing a bunch of repeated information in
  70 flags over and over.
  71
  72 An example ~/.cobra.yaml file:
  73
  74 ```yaml
  75 author: Steve Francia <spf@spf13.com>
  76 license: MIT
  77 ```
  78
  79 You can specify no license by setting `license` to `none` or you can specify
  80 a custom license:
  81
  82 ```yaml
  83 license:
  84   header: This file is part of {{ .appName }}.
  85   text: |
  86     {{ .copyright }}
  87
  88     This is my license. There are many like it, but this one is mine.
  89     My license is my best friend. It is my life. I must master it as I must
  90     master my life.
  91 ```
  92
  93 You can also use built-in licenses. For example, **GPLv2**, **GPLv3**, **LGPL**,
  94 **AGPL**, **MIT**, **2-Clause BSD** or **3-Clause BSD**.