This content originally appeared on DEV Community and was authored by Div Rhino
Originally posted on divrhino.com
This tutorial will guide us through building an interactive CLI app with Go, Cobra and promptui. We will learn how to prompt the user for input data and persist this data to an SQLite database. Unlike the previous app we built, this experience will feel more like a two way conversation.
Prerequisites
To follow along with this tutorial, you will need to have Go and the Cobra generator installed.
Installation guides:
Demo of what we're building
We will build a note-taking app called Studybuddy. The app will ask us a series of questions and save our answers as a note. We will then be able to see all the notes we've saved. The following video demonstrates some interactive behaviour we will build:
Commands we will implement
This article will focus on implementing interactivity with promptui. We will create several commands to achieve our goal.
-
studybuddy init- creates a database -
studybuddy note- displays information about commands related to notes -
studybuddy note new- opens a prompt to collect data from the user -
studybuddy note list- displays all the notes we've created
Setting up a cobra app
We will be using the cobra package to give us the functionality we need to build our CLI app. We will only need the ability to create a handful of commands and subcommands, so our cobra app will be very simple.
Starting in our Sites folder, or wherever you keep your projects, we will create a new project folder called studybuddy. Then we will change into it
mkdir -p studybuddy && cd studybuddy
Using the cobra generator, we can initialise a new cobra app. It is a good idea to name your project using the URL where it can be downloaded. I will use my Github repo URL as the name of my package. Please feel free to substitute the following command with your own Github account or personal website
cobra init --pkg-name github.com/divrhino/studybuddy
We will be using go modules to manage our project dependencies, so we can set it up using the same package name we used in the above cobra init command
go mod init github.com/divrhino/studybuddy
To add module requirements and sums, let's run
go mod tidy
Then we should also update descriptions in cmd/root.go file
Use: "studybuddy",
Short: "Use studybuddy to learn and retain vocabulary",
Long: `Learn a new language with the studybuddy CLI app by your side`,
And that's our basic cobra app. Let's build it and try it out. Run the following command to build the current project
go build .
An executable binary will be created in your project folder. We have not installed it in our GOPATH so we can't execute it simply by running studybuddy in the terminal. Instead we can run it relative to the current project directory
./studybuddy
If all has gone according to plan, we should get a print out in the terminal showing a bunch of information about our new CLI app.
Opening the database connection
In order to read and write to our database, we will need to open the database connection pool. To do this, we must first create a new SQLite database. As the name suggests, SQLite is a "lite" database, so it is less complicated than something like Postgres. This makes it a great choice for a situation like ours where the primary focus is not the database.
All our database-related functionality should be kept in an appropriate place. Let's create a data folder and also create a file called data.go within it
mkdir data
touch data/data.go
Then let's install the go-sqlite3 package so we can use it in our project
go get github.com/mattn/go-sqlite3
Opening up data/data.go, we can start by importing the database/sql and go-sqlite3 packages. These are the 2 packages we need to work with SQLite in our app
package data
import (
"database/sql"
_ "github.com/mattn/go-sqlite3"
)
We can create our function that will open up the database connection pool. We can start writing our code after the imports. In the following code:
- We set up a package-level variable called
dbto hold our database connection pool. This variable will be used in several functions. - We set up
OpenDatabase()function. - Then inside the body of
OpenDatabase(), we declare a variable forerrthat we will use later in thesql.Open()function - Next we use
sql.Open()to open up a connection pool, passing in our driver name (sqlite3) and the path to our database. Notice that we are not re-declaring thedbor theerrvariables. We want to assign the return value fromsql.Open()to the package-leveldbvariable we declared previously - We do some quick error handling before we move on
- Then we just return a
db.Ping()to verify that the connection is alive
var db *sql.DB
func OpenDatabase() error {
var err error
db, err = sql.Open("sqlite3", "./sqlite-database.db")
if err != nil {
return err
}
return db.Ping()
}
Now that our OpenDatabase() function is ready, will call it from func main(). We do this so the entire app can have access to the connection pool. Our entire main.go file should look something like this:
package main
import (
"github.com/divrhino/studybuddy/cmd"
"github.com/divrhino/studybuddy/data"
)
func main() {
data.OpenDatabase()
cmd.Execute()
}
Creating the database table
Next, we will need to set up a table into which we can insert our study notes.
We can create a function to create a new table called studybuddy. Inside data/data.go, and in the following code:
- we set up
CreateTable()function - Inside the body of the
CreateTable()function, we set up a variable calledcreateTableSQLto hold the SQL statement we need to create a table with the necessary columns. i.e.idNote,word,definition,category - We prepare the
SQLstatement using thedb.Prepare()method on the package-leveldbvariable we created earlier - If
db.Prepare()returns an error, we do some quick error handling - Then we execute the statement using
Exec() - Here as well, just so we can see what's happening, we log a message using
log.Println
func CreateTable() {
createTableSQL := `CREATE TABLE IF NOT EXISTS studybuddy (
"idNote" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
"word" TEXT,
"definition" TEXT,
"category" TEXT
);`
statement, err := db.Prepare(createTableSQL)
if err != nil {
log.Fatal(err.Error())
}
statement.Exec()
log.Println("Studybuddy table created")
}
We will be using this CreateTable() function in our init command, which we will create next.
The init command
Our first custom command will be the init command. We want to run this command to create a new database table. The database connection pool will also open because once we start using the app, func main() will call the OpenDatabase() function.
Making sure we're in our project directory, let's create our init command
cobra add init
Then let's open the newly created cmd/init.go file to quickly update the short and long descriptions. Our short and long descriptions do not have to be the same. But since we don't want to spend too much time worrying about the content here, we will just have them be the same.
Short: "Initialise a new studybuddy database and table",
Long: `Initialise a new studybuddy database and table.`,
Still in the cmd/init.go file, we will:
- import the
datapackage we just created - Inside the
Runfunction of theinitCmd, we will call the function we just created above. i.e.CreateTable()
package cmd
import (
"github.com/divrhino/studybuddy/data"
"github.com/spf13/cobra"
)
var initCmd = &cobra.Command{
Use: "init",
Short: "Initialise a new studybuddy database and table",
Long: `Initialise a new studybuddy database and table.`,
Run: func(cmd *cobra.Command, args []string) {
data.CreateTable()
},
}
func init() {
rootCmd.AddCommand(initCmd)
}
Now we can build our app
go build .
In the terminal, we can now run the following command. We will know that it's working when a file called sqlite-database.db appears in our project root.
./studybuddy init
The base note command
With the initial database setup sorted out, we can move on to adding commands that are directly related to note-taking. The next command we will implement is the base note command. This command won't actually do a whole lot. It will just allow us to get more information about its subcommands
Using the cobra generator, we can go ahead and add the note command
cobra add note
Now we just have to do two things:
- First, we have to update the command descriptions
- Second, we have to remove the
Runfield. RemovingRunmakes this command behave more like thehelpcommand
Our whole noteCmd variable should look like this:
var noteCmd = &cobra.Command{
Use: "note",
Short: "A note can be anything you'd like to study and review.",
Long: `A note can be anything you'd like to study and review.`,
}
And that's it for the base note command. Let's build the app
go build .
Then run the binary from within the project directory
./studybuddy note
If everything was built correctly, we should get a print out in the terminal with some information about our new note command.
The note new command
This is the most involved section of the tutorial because this is where the bulk of the interactivity occurs. Here we will utilise promptui to help us accept user input data. Then we will persist it to our database.
First we need to create a subcommand under the previously-created note command. When used, the subcommand will take this form: studybuddy note new. In the terminal, execute the following line:
cobra add new -p 'noteCmd'
For this command as well, we will need to update the descriptions
Use: "new",
Short: "Creates a new studybuddy note",
Long: `Creates a new studybuddy note`,
We will need a way to get user input. We can use the promptui package to help us. We will have to install it first by running the following command in the terminal:
go get github.com/manifoldco/promptui
Every prompt has a similar shape, so we can go ahead and create a custom promptContent struct type
type promptContent struct {
errorMsg string
label string
}
We should probably also import the promptui package along with the other packages we need before we continue
package cmd
import (
"errors"
"fmt"
"os"
"github.com/manifoldco/promptui"
"github.com/spf13/cobra"
)
A prompt from the promptui package has a few key concepts:
- validate - a function to validate the user's input
- templates - used to style text for different state messages
- prompt - the actual prompt struct. Running the prompt will allow us to collect data from the user. This feedback will be stored as
result
func promptGetInput(pc promptContent) string {
validate := func(input string) error {
if len(input) <= 0 {
return errors.New(pc.errorMsg)
}
return nil
}
templates := &promptui.PromptTemplates{
Prompt: "{{ . }} ",
Valid: "{{ . | green }} ",
Invalid: "{{ . | red }} ",
Success: "{{ . | bold }} ",
}
prompt := promptui.Prompt{
Label: pc.label,
Templates: templates,
Validate: validate,
}
result, err := prompt.Run()
if err != nil {
fmt.Printf("Prompt failed %v\n", err)
os.Exit(1)
}
fmt.Printf("Input: %s\n", result)
return result
}
After prompting the user for data, we want to use this data to create a new note. Using the custom promptContent struct we created, above, we will set up a prompt to capture a word and a definition for the word.
func createNewNote() {
wordPromptContent := promptContent{
"Please provide a word.",
"What word would you like to make a note of?",
}
word := promptGetInput(wordPromptContent)
definitionPromptContent := promptContent{
"Please provide a definition.",
fmt.Sprintf("What is the definition of %s?", word),
}
definition := promptGetInput(definitionPromptContent)
}
While we can prompt the user for text input, we can also give the user some options to choose from. We achieve this by using SelectWithAdd from promptui. In the following code:
- We start with some pre-determined
items, which will be of type[]string - We give the user the option of adding their own category by adding the label
Other - We set the initial
indexto-1because this index will never actually be present insideitems - As long as the index is
-1, the prompt is kept open and more categories can be appended to theitemsslice - Once the user chooses an item, the prompt will close and the result will be returned
func promptGetSelect(pc promptContent) string {
items := []string{"animal", "food", "person", "object"}
index := -1
var result string
var err error
for index < 0 {
prompt := promptui.SelectWithAdd{
Label: pc.label,
Items: items,
AddLabel: "Other",
}
index, result, err = prompt.Run()
if index == -1 {
items = append(items, result)
}
}
if err != nil {
fmt.Printf("Prompt failed %v\n", err)
os.Exit(1)
}
fmt.Printf("Input: %s\n", result)
return result
}
Once we're done with our promptGetSelect function, we can return to our createNewNote() function to capture the category
func createNewNote() {
wordPromptContent := promptContent{
"Please provide a word.",
"What word would you like to make a note of?",
}
word := promptGetInput(wordPromptContent)
definitionPromptContent := promptContent{
"Please provide a definition.",
fmt.Sprintf("What is the definition of the %s?", word),
}
definition := promptGetInput(definitionPromptContent)
categoryPromptContent := promptContent{
"Please provide a category.",
fmt.Sprintf("What category does %s belong to?", word),
}
category := promptGetSelect(categoryPromptContent)
}
We are able to capture input data from the user about notes, but we haven't created a function to insert the notes into our database, so let's do that now. Back in data/data.go, we need to create another method that interacts with our database. This time we want to INSERT data:
func InsertNote(word string, definition string, category string) {
insertNoteSQL := `INSERT INTO studybuddy(word, definition, category) VALUES (?, ?, ?)`
statement, err := db.Prepare(insertNoteSQL)
if err != nil {
log.Fatalln(err)
}
_, err = statement.Exec(word, definition, category)
if err != nil {
log.Fatalln(err)
}
log.Println("Inserted study note successfully")
}
Now we're ready to insert notes into the database. Jumping back into our new command in the file new.go, we'll have to import the data package into cmd/new.go
import (
...
"github.com/divrhino/studybuddy/data"
...
)
At the bottom of our createNewNote() function, call data.InsertNote() and pass in the word, definition and category data we collected from the user:
func createNewNote() {
wordPromptContent := promptContent{
"Please provide a word.",
"What word would you like to make a note of?",
}
word := promptGetInput(wordPromptContent)
definitionPromptContent := promptContent{
"Please provide a definition.",
fmt.Sprintf("What is the definition of the %s?", word),
}
definition := promptGetInput(definitionPromptContent)
categoryPromptContent := promptContent{
"Please provide a category.",
fmt.Sprintf("What category does %s belong to?", word),
}
category := promptGetSelect(categoryPromptContent)
data.InsertNote(word, definition, category)
}
Then to tie everything up, we have to call our completed createNewNote() function inside Run:
var newCmd = &cobra.Command{
Use: "new",
Short: "Create a new note to study",
Long: `Create a new note to study.`,
Run: func(cmd *cobra.Command, args []string) {
createNewNote()
},
}
Let's build everything so we can test our changes
go build .
Then run the note new command to trigger out little "interview":
./studybuddy note new
Add a few notes so we have something to see in the next section.
The note list command
This final command will give us the ability to display all our notes. We will need a way to retrieve all our records from the database.
Back in the data/data.go files, we can create a function to do that. In the following code:
- we set up a function called
DisplayAllNotes() - We then set up an
SQLquery to select everything from thestudybuddytable and order the results byword - We do some quick error handling
- Then we refer the closing of the row
- We loop through the rows and print out the columns in a loosely formatted string
func DisplayAllNotes() {
row, err := db.Query("SELECT * FROM studybuddy ORDER BY word")
if err != nil {
log.Fatal(err)
}
defer row.Close()
for row.Next() {
var idNote int
var word string
var definition string
var category string
row.Scan(&idNote, &word, &definition, &category)
log.Println("[", category, "] ", word, "—", definition)
}
}
We should also remember to create our list subcommand. When used, the subcommand will take this form: studybuddy note list. In the terminal, execute the following line:
cobra add list -p 'noteCmd'
Now we can open up cmd/list.go and update it. In the following code:
- We import the
datapackage. - We update the
ShortandLongdescriptions - We call
data.DisplayAllNotes()insideRun
package cmd
import (
"github.com/divrhino/studybuddy/data"
"github.com/spf13/cobra"
)
// listCmd represents the list command
var listCmd = &cobra.Command{
Use: "list",
Short: "See a list of all notes you've added",
Long: `See a list of all notes you've added.`,
Run: func(cmd *cobra.Command, args []string) {
data.DisplayAllNotes()
},
}
func init() {
noteCmd.AddCommand(listCmd)
}
Build the app
go build .
And run the following command to see a list of all our notes:
./studybuddy note list
Going further
Interactive CLI apps are a simple, yet powerful tool to have at your disposal. You can combine them with webscrapers or other techniques to build custom productivity apps and beef up your personal workflow.
If you’d like to extend this project further, you can consider doing the following:
- Add a feature that lets you
testyourself. Display each word in a question and execute a prompt to collect theanswerto test questions. - Add a feature that allows you to see which words you have trouble remembering.
Conclusion
In this tutorial we learnt how to build an interactive CLI app that we can use to save fun and interesting new words.
If you enjoyed this article and you'd like more, consider subscribing to Div Rhino on YouTube.
Congratulations, you did great. Keep learning and keep coding. Bye for now, <3.
divrhino
/
studybuddy
Build an interactive CLI application with Go, Cobra and promptui. Video tutorial available on the Div Rhino YouTube channel.
Build an interactive CLI app with Go, Cobra and promptui
- Text tutorial: https://divrhino.com/articles/build-interactive-cli-app-with-go-cobra-promptui
- Video tutorial: https://www.youtube.com/watch?v=so3VZwdWcBg
This content originally appeared on DEV Community and was authored by Div Rhino
Div Rhino | Sciencx (2021-07-05T11:56:22+00:00) How to build an interactive CLI app with Go, Cobra & promptui. Retrieved from https://www.scien.cx/2021/07/05/how-to-build-an-interactive-cli-app-with-go-cobra-promptui/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.