Command-Line Programs in Go

$ mkdir -p bookshelf/cmd/shelf && cd bookshelf
$ go mod init example.com/bookshelf
$ go get github.com/urfave/cli/v3@v3.14.0 golang.org/x/term@v0.47.0

// cmd/shelf/main.go
package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"os/signal"
	"strconv"
	"strings"
	"syscall"

	"github.com/urfave/cli/v3"
)

// version is stamped at build time: go build -ldflags "-X main.version=1.4.0"
var version = "dev"

// Exit statuses of shelf. 0 is success and 1 is any other failure.
const (
	exitFailure  = 1
	exitUsage    = 2
	exitNotFound = 3
	exitConflict = 4
)

// statusError is an error that carries the process exit status.
type statusError struct {
	status int
	msg    string
}

func (e *statusError) Error() string { return e.msg }
func (e *statusError) Status() int   { return e.status }

type book struct {
	ID     int    `json:"id"`
	Title  string `json:"title"`
	Author string `json:"author"`
	LentTo string `json:"lent_to,omitempty"`
}

func load(path string) ([]book, error) {
	data, err := os.ReadFile(path)
	if errors.Is(err, os.ErrNotExist) {
		return nil, nil // an absent file is an empty bookshelf
	}
	if err != nil {
		return nil, err
	}
	var books []book
	if err := json.Unmarshal(data, &books); err != nil {
		return nil, fmt.Errorf("%s: %w", path, err)
	}
	return books, nil
}

func save(path string, books []book) error {
	data, err := json.MarshalIndent(books, "", "  ")
	if err != nil {
		return err
	}
	return os.WriteFile(path, data, 0o644)
}

// dataFlag is defined once and attached to every command that reads the bookshelf.
func dataFlag() cli.Flag {
	return &cli.StringFlag{
		Name:    "data",
		Aliases: []string{"d"},
		Usage:   "path of the bookshelf file",
		Value:   "shelf.json",
		Sources: cli.EnvVars("SHELF_DATA"),
	}
}

func newApp() *cli.Command {
	return &cli.Command{
		Name:                  "shelf",
		Usage:                 "search and lend the books on your shelf",
		Version:               version,
		EnableShellCompletion: true,
		Commands: []*cli.Command{
			{
				Name:      "search",
				Aliases:   []string{"s"},
				Usage:     "list books whose title or author contains QUERY",
				ArgsUsage: "QUERY",
				Flags: []cli.Flag{
					dataFlag(),
					&cli.BoolFlag{Name: "json", Usage: "print a JSON array instead of a table"},
				},
				Action: search,
			},
			{
				Name:      "lend",
				Usage:     "lend the book with the given ID",
				ArgsUsage: "ID",
				Flags: []cli.Flag{
					dataFlag(),
					&cli.StringFlag{Name: "to", Usage: "who borrows the book", Required: true},
				},
				Action: lend,
			},
			{
				Name:  "login",
				Usage: "read a shelfd token from the terminal or from standard input",
				Action: func(ctx context.Context, cmd *cli.Command) error {
					token, err := readToken()
					if err != nil {
						return err
					}
					fmt.Fprintf(os.Stderr, "shelf: token read (%d bytes)\n", len(token))
					return nil
				},
			},
			{
				Name:  "browse",
				Usage: "browse the shelf interactively (needs a terminal)",
				Flags: []cli.Flag{dataFlag()},
				Action: func(ctx context.Context, cmd *cli.Command) error {
					books, err := load(cmd.String("data"))
					if err != nil {
						return err
					}
					titles := make([]string, len(books))
					for i, b := range books {
						titles[i] = b.Title + " - " + b.Author
					}
					return browse(ctx, titles)
				},
			},
		},
	}
}

func search(ctx context.Context, cmd *cli.Command) error {
	if cmd.NArg() != 1 {
		return &statusError{exitUsage, "usage: shelf search QUERY"}
	}
	books, err := load(cmd.String("data"))
	if err != nil {
		return err
	}
	query := strings.ToLower(cmd.Args().First())
	var found []book
	for _, b := range books {
		if strings.Contains(strings.ToLower(b.Title+" "+b.Author), query) {
			found = append(found, b)
		}
	}
	if len(found) == 0 {
		return &statusError{exitNotFound, "no book matches " + strconv.Quote(cmd.Args().First())}
	}
	if cmd.Bool("json") {
		enc := json.NewEncoder(os.Stdout)
		enc.SetIndent("", "  ")
		return enc.Encode(found)
	}
	for _, b := range found {
		fmt.Printf("%3d  %-32s %s\n", b.ID, b.Title, b.Author)
	}
	return nil
}

func lend(ctx context.Context, cmd *cli.Command) error {
	id, err := strconv.Atoi(cmd.Args().First())
	if err != nil {
		return &statusError{exitUsage, "usage: shelf lend --to NAME ID"}
	}
	path := cmd.String("data")
	books, err := load(path)
	if err != nil {
		return err
	}
	for i := range books {
		if books[i].ID != id {
			continue
		}
		if books[i].LentTo != "" {
			return &statusError{exitConflict, fmt.Sprintf("book %d is already lent to %s", id, books[i].LentTo)}
		}
		if err := ctx.Err(); err != nil {
			return err // interrupted before anything was written
		}
		books[i].LentTo = cmd.String("to")
		return save(path, books)
	}
	return &statusError{exitNotFound, fmt.Sprintf("no book with ID %d", id)}
}

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	code := run(ctx, os.Args)
	stop() // os.Exit skips deferred calls, so release the signal handler explicitly
	os.Exit(code)
}

// run is the testable part of main: it returns the exit status instead of exiting.
func run(ctx context.Context, args []string) int {
	err := newApp().Run(ctx, args)
	if err == nil {
		return 0
	}
	var s interface{ Status() int }
	switch {
	case errors.As(err, &s):
		fmt.Fprintln(os.Stderr, "shelf:", err)
		return s.Status()
	case errors.Is(err, context.Canceled):
		fmt.Fprintln(os.Stderr, "shelf: interrupted")
		return 130 // the shell convention 128 + SIGINT; meaningless on Windows
	default:
		fmt.Fprintln(os.Stderr, "shelf:", err)
		return exitFailure
	}
}

$ shelf search tolkien --json
$ shelf lend --to Ana 3
$ shelf lend --to Ben 3; echo "status $?"
shelf: book 3 is already lent to Ana
status 4
$ SHELF_DATA=/srv/shelf.json shelf s hobbit
$ shelf --version

# macOS and Linux (sh, bash, zsh)
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -trimpath -ldflags "-s -w -X main.version=1.4.0" -o dist/shelf.exe ./cmd/shelf
CGO_ENABLED=0 GOOS=linux   GOARCH=arm64 go build -trimpath -ldflags "-s -w -X main.version=1.4.0" -o dist/shelf-linux-arm64 ./cmd/shelf
CGO_ENABLED=0 GOOS=darwin  GOARCH=arm64 go build -trimpath -ldflags "-s -w -X main.version=1.4.0" -o dist/shelf-darwin-arm64 ./cmd/shelf

# Windows PowerShell and PowerShell 7
$env:CGO_ENABLED = "0"; $env:GOOS = "linux"; $env:GOARCH = "amd64"
go build -trimpath -o dist/shelf-linux-amd64 ./cmd/shelf
Remove-Item Env:GOOS, Env:GOARCH   # go back to building for this machine

:: Windows cmd.exe
set CGO_ENABLED=0
set GOOS=linux
set GOARCH=amd64
go build -trimpath -o dist\shelf-linux-amd64 .\cmd\shelf

$ go install example.com/bookshelf/cmd/shelf@v1.4.0
$ go install example.com/bookshelf/cmd/shelf@latest
$ go install ./cmd/shelf          # from a checkout: build the local code
$ go env GOBIN GOPATH