Posts Talks Categories $whoami

Contents

Create a CLI with Cobra in Go

Gaurav Gahlot included in Go
   1132 words   6 minutes 

In this post, we talk about how we can create a simple CLI with Cobra in Go. Cobra is a library for creating powerful modern CLI interfaces similar to git & go tools.


Introduction

The term CLI stands for Command Line Interface, which is a method of interacting with a computer program through text-based commands entered in a terminal or console. It allows users to perform various tasks by typing specific commands and parameters instead of using a graphical user interface (GUI).

While CLI help improves efficiency, automation, and flexibility, they are typically lightweight and require fewer system resources as compared to GUI applications. However, it is the responsibility of the developer to ensure that the CLI is easy to use, provides help documentation, and also has autocomplete features.

In this article, we will be creating a simple, easy-to-use CLI in Go using the Cobra package. Let’s get started!


In case you prefer following along a video, you can checkout the following video on my YouTube channel.


Project Setup

I would assume you have a working Go environment on your system; if not, you can download and install it from the official page.

Now, let’s start by creating a directory called greeter. Then change into the directory and initialize the Go module using the go mod init command.


 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

~/workspace
➜ mkdir greeter

~/workspace
➜ cd greeter

~/workspace/greeter
➜ go mod init "greeter"
go: creating new go.mod: module greeter

~/workspace/greeter via ?? v1.20.2
➜ ls -l
total 8
-rw-r--r--  1 gaurav  root  24 Jun 14 23:55 go.mod

Open the directory in your favorite code editor because it’s time we write some code. I prefer using VIM or VS Code.


The Code

We will be creating a basic CLI named greeter using the Cobra library. The CLI has two commands: the root command, which simply prints a welcome message, and the greet command, which takes an argument (a name) and greets the person by their name.

Start by creating a file called main.go in the current directory and follow along. We start by importing the required packages.

1
2
3
4
5
6

import (
	"fmt"
	"os"

	"github.com/spf13/cobra"
)

We imported:

  • fmt package for printing messages
  • os package for handling operating system-related functionality
  • cobra package, which is a popular library for building command-line interfaces in Go.

Note that the first two packages are available in the Go standard library, while Cobra is an external package that we need to get before we can use it.

In order to get the package, switch back to the terminal and execute the go-get command shown below.

1
2
3
4
5

~/workspace/greeter via 🐹 v1.20.2
➜ go get "github.com/spf13/cobra"
go: added github.com/inconshreveable/mousetrap v1.1.0
go: added github.com/spf13/cobra v1.7.0
go: added github.com/spf13/pflag v1.0.5

Inside the main function, we create the root command using cobra.Command.

1
2
3
4
5
6
7
8

rootCmd := &cobra.Command{
	Use:   "greeter",
	Short: "A basic CLI example",
	Long:  "A basic CLI example using Cobra",
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("Welcome to Greeter!")
	},
}
  • Use - sets the name of our CLI tool (greeter)
  • Short - provides a brief description
  • Long - provides a more detailed description
  • Run - defines the function that will be executed when this command is invoked; in our case, it simply prints a welcome message.

Next, we define a subcommand named greet:

1
2
3
4
5
6
7
8
9

greetCmd := &cobra.Command{
	Use:   "greet",
	Short: "Greet someone",
	Long:  "Greet someone by their name",
	Args:  cobra.ExactArgs(1),
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Printf("Hello, %s!\n", args[0])
	},
}

Similar to the root command, we provide a name (greet), a short description, and a long explanation for the subcommand. The Args field specifies that this command requires exactly one argument. The Run field contains a function that will be executed when this command is invoked. It retrieves the provided name argument and greets the person using fmt.Printf.

We add the greetCmd as a subcommand to the root command.

1

rootCmd.AddCommand(greetCmd)

This line connects the greetCmd as a subcommand to the rootCmd.

Finally, we execute the root command and handle any errors:

1
2
3
4

if err := rootCmd.Execute(); err != nil {
    fmt.Println(err)
    os.Exit(1)
}

The Execute method runs the CLI and processes the provided command-line arguments. If there’s an error during execution, it will be printed, and the program will exit with a non-zero status code.

Here is the complete code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

package main

import (
	"fmt"
	"os"

	"github.com/spf13/cobra"
)

func main() {
	rootCmd := &cobra.Command{
		Use:   "greeter",
		Short: "A basic CLI example",
		Long:  "A basic CLI example using Cobra",
		Run: func(cmd *cobra.Command, args []string) {
			fmt.Println("Welcome to Greeter!")
		},
	}

	greetCmd := &cobra.Command{
		Use:   "greet",
		Short: "Greet someone",
		Long:  "Greet someone by their name",
		Args:  cobra.ExactArgs(1),
		Run: func(cmd *cobra.Command, args []string) {
			fmt.Printf("Hello, %s!\n", args[0])
		},
	}

	rootCmd.AddCommand(greetCmd)

	if err := rootCmd.Execute(); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
}

Build and Run

We can now build our CLI binary by executing the following command.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

~/workspace/greeter via 🐹 v1.20.2
➜ go build -o greeter main.go

~/workspace/greeter via 🐹 v1.20.2
➜ ls -l
total 8520
-rw-r--r--  1 gaurav  root      180 Jun 15 00:10 go.mod
-rw-r--r--  1 gaurav  root      896 Jun 15 00:10 go.sum
-rwxr-xr-x  1 gaurav  root  4346976 Jun 15 00:27 greeter
-rw-r--r--  1 gaurav  root      651 Jun 15 00:09 main.go

Now, if we run the CLI without any subcommand, we get the welcome message.

1
2
3

~/workspace/greeter via 🐹 v1.20.2
➜ ./greeter
Welcome to Greeter!

A good CLI always has good documentation. We can check the documentation generated for our CLI as well.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

~/workspace/greeter via 🐹 v1.20.2
? ./greeter --help
A basic CLI example using Cobra

Usage:
  greeter [flags]
  greeter [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  greet       Greet someone
  help        Help about any command

Flags:
  -h, --help   help for greeter

Use "greeter [command] --help" for more information about a command.

As a final test, let’s execute the greet subcommand as well.

1
2
3

~/workspace/greeter via 🐹 v1.20.2
? ./greeter greet Gaurav
Hello, Gaurav!

Conclusion

In this article, we have created a simple yet well-documented CLI in Go using Cobra. In the posts to follow, we will restructure our project to be more organized and also add unit tests for the CLI.


Please share your questions and valuable feedback through comments.

Thank you!

Updated on 2024-10-16
Read Markdown
 Go, Cobra
Back | Home