Cobra — Modern CLI Framework for Go Applications

What it is

Cobra is a Go library for building command-line applications with subcommands, flags, auto-generated help text, and shell completions. It is the most widely used CLI framework in the Go ecosystem, powering the CLIs of Kubernetes (kubectl), GitHub CLI (gh), Docker, Hugo, and hundreds of other tools.

Cobra targets Go developers building CLI tools that need structured subcommands (like git commit, docker run, or kubectl apply). It handles argument parsing, validation, help generation, and man page creation.

How it saves time or tokens

Cobra eliminates the boilerplate of parsing flags, validating arguments, and generating help text. Its code generator scaffolds new commands with a single command. You focus on business logic while Cobra handles the CLI framework concerns.

Shell completion scripts (bash, zsh, fish, PowerShell) are auto-generated from your command definitions. Without Cobra, writing and maintaining completion scripts is a manual, error-prone process.

How to use

1. Install Cobra and initialize a project:

go install github.com/spf13/cobra-cli@latest
cobra-cli init myapp
cd myapp

1. Add a subcommand:

cobra-cli add serve
cobra-cli add migrate

1. Implement the command logic in cmd/serve.go:

var serveCmd = &cobra.Command{
    Use:   "serve",
    Short: "Start the HTTP server",
    Run: func(cmd *cobra.Command, args []string) {
        port, _ := cmd.Flags().GetInt("port")
        fmt.Printf("Starting server on port %d\n", port)
    },
}

func init() {
    serveCmd.Flags().IntP("port", "p", 8080, "Port to listen on")
    rootCmd.AddCommand(serveCmd)
}

Example

A complete CLI with persistent flags and nested subcommands:

package main

import (
    "fmt"
    "github.com/spf13/cobra"
)

var verbose bool

var rootCmd = &cobra.Command{
    Use:   "myapp",
    Short: "My application CLI",
}

var deployCmd = &cobra.Command{
    Use:   "deploy [environment]",
    Short: "Deploy to an environment",
    Args:  cobra.ExactArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Deploying to %s (verbose=%v)\n", args[0], verbose)
    },
}

func main() {
    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Verbose output")
    rootCmd.AddCommand(deployCmd)
    rootCmd.Execute()
}

Related on TokRepo

• AI tools for coding -- Development frameworks and libraries
• Automation tools -- CLI tools for automation workflows

Common pitfalls

• Putting all command logic in the Run function. Extract business logic into separate packages and keep commands thin. This makes the logic testable independently of the CLI framework.
• Overusing persistent flags. Persistent flags propagate to all subcommands. If a flag only applies to one command, make it a local flag to keep help text clean.
• Forgetting to call cobra.CheckErr() on errors. Cobra provides consistent error handling. Use it instead of log.Fatal() to get proper exit codes and error formatting.