Cobra Documentation and Scaffolding Generators

Doc generation

Cobra can generate documentation from your command tree in multiple formats. Import the cobra/doc sub-package:

go get github.com/spf13/cobra/doc

Markdown

import "github.com/spf13/cobra/doc"

err := doc.GenMarkdownTree(rootCmd, "/tmp/docs/")
// generates /tmp/docs/myapp.md, /tmp/docs/myapp_serve.md, etc.

// Single command
var buf bytes.Buffer
doc.GenMarkdown(rootCmd, &buf)

Man pages

header := &doc.GenManHeader{
    Title:   "MYAPP",
    Section: "1",
    Date:    &time.Time{},
    Source:  "myapp v1.0.0",
    Manual:  "User Commands",
}
err := doc.GenManTree(rootCmd, header, "/usr/local/share/man/man1/")

YAML

err := doc.GenYamlTree(rootCmd, "/tmp/docs/")

RST (reStructuredText)

err := doc.GenReSTTree(rootCmd, "/tmp/docs/")

cobra-cli scaffolder

cobra-cli generates command files and wires them into your project:

go get -tool github.com/spf13/cobra-cli@latest

# Initialize a new cobra project
go tool cobra-cli init myapp

# Add a subcommand
go tool cobra-cli add serve
go tool cobra-cli add migrate

# Add with a parent other than root
cobra-cli add list --parent serve

Generated files follow the standard pattern:

// cmd/serve.go
var serveCmd = &cobra.Command{
    Use:   "serve",
    Short: "A brief description of your command",
    RunE: func(cmd *cobra.Command, args []string) error {
        return nil
    },
}

func init() {
    rootCmd.AddCommand(serveCmd)
}

cobra-cli is optional — many teams write command files by hand following the same pattern.

Help and usage template customization

Override the default help template:

rootCmd.SetHelpTemplate(`
Usage:  {{.UseLine}}
{{if .HasAvailableSubCommands}}
Commands:
{{range .Commands}}{{if .IsAvailableCommand}}  {{rpad .Name .NamePadding }} {{.Short}}
{{end}}{{end}}{{end}}
Flags:
{{.LocalFlags.FlagUsages | trimRightSpace}}
`)

Override the usage function entirely:

rootCmd.SetUsageFunc(func(cmd *cobra.Command) error {
    fmt.Fprintf(cmd.OutOrStdout(), "Custom usage for %s\n", cmd.Name())
    return nil
})

Common template functions available: rpad, trimRightSpace, gt, eq.

2.2 KiB Raw Blame History