What I Talk About When I Talk About CLI Tool By Golang #gocon

Slide 1

Slide 1 text

WHAT I TALK ABOUT  WHEN I TALK ABOUT WRITING CLI TOOL BY GOLANG

Slide 2

Slide 2 text

TAICHI NAKASHIMA @deeeet @tcnksm

Slide 3

Slide 3 text

No content

Slide 4

Slide 4 text

No content

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

WHAT I TALK ABOUT  WHEN I TALK ABOUT WRITING CLI TOOL BY GOLANG

Slide 8

Slide 8 text

THINK AGAIN Why I choose Golang for CLI tool ?

Slide 9

Slide 9 text

Easy to Cross-Compile Easy to Distribute Performance

Slide 10

Slide 10 text

Cross-Compile Compile to windows exe from OS X $ GOOS=windows GOARCH=amd64 go build -o hello.exe

Slide 11

Slide 11 text

$ curl -L https://github.com/docker/machine/releases/download/ v0.3.0/docker-machine_darwin-amd64 \ > /usr/local/bin/docker-machine $ chmod +x /usr/local/bin/docker-machine Easy to Distribute e.g., docker/docker-machine

Slide 12

Slide 12 text

$ time heroku apps >/dev/null real 0m3.830s $ time hk apps >/dev/null real 0m0.785s e.g., heroku/hk Performance

Slide 13

Slide 13 text

Easy to Cross-Compile Easy to Distribute Performance

Slide 14

Slide 14 text

What is GOOD CLI tool ?

Slide 15

Slide 15 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

How to do that by Golang ?

Slide 18

Slide 18 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 19

Slide 19 text

Do ONE thing well Don’t worry, your tool will be more and more complex (e.g., tcnksm/ghr) flags.StringVar(&githubAPIOpts.OwnerName, []string{"u", "-username"}, "", "") flags.StringVar(&githubAPIOpts.RepoName, []string{"r", "-repository"}, "", "") flags.StringVar(&githubAPIOpts.Token, []string{"t", "-token"}, "", "") flags.StringVar(&githubAPIOpts.Commitish, []string{"c", "-commitish"}, "", "") flags.BoolVar(&githubAPIOpts.Draft, []string{"-draft"}, false, "") flags.BoolVar(&githubAPIOpts.Prerelease, []string{"-prerelease"}, false, "") flags.IntVar(&ghrOpts.Parallel, []string{"p", "-parallel"}, -1, "") flags.BoolVar(&ghrOpts.Replace, []string{"-replace"}, false, "") flags.BoolVar(&ghrOpts.Delete, []string{"-delete"}, false, "") flags.BoolVar(&stat, []string{"-stat"}, false, “") version := flags.Bool([]string{"v", "-version"}, false, "") debug := flags.Bool([]string{"-debug"}, false, "")

Slide 20

Slide 20 text

Do ONE thing well `ls` has diﬀerent 37 flags ls [-ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1] [file ...]

Slide 21

Slide 21 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 22

Slide 22 text

LONG HISTORY Should follow its convention/standard

Slide 23

Slide 23 text

Intuitive UI/UX What is CLI UI convention/standard ? # Executable + flags + args pattern $ grep —i -C 4 "some string" /tmp # Executable + commands + args pattern $ git --no-pager push -v origin master

Slide 24

Slide 24 text

FLAG PATTERN flag docker/mflag ogier/pflag jessevdk/go-flags

Slide 25

Slide 25 text

FLAG PATTERN flag docker/mflag ogier/pflag jessevdk/go-flags

Slide 26

Slide 26 text

Intuitive UI/UX e.g., docker/mflag // Easy to provide short option and long option version := mflag.Bool([]string{"v", "-version"}, false, "")

Slide 27

Slide 27 text

COMMANDS PATTERN codegangsta/cli … docker/xxx, cloudfoudry/cli mitchellh/cli … hashicorp/xxx, tcnksm/gcli spf13/cobra … hugo docopt/docopt.go

Slide 28

Slide 28 text

COMMANDS PATTERN codegangsta/cli … docker/xxx, cloudfoudry/cli mitchellh/cli … hashicorp/xxx, tcnksm/gcli spf13/cobra … hugo docopt/docopt.go

Slide 29

Slide 29 text

Intuitive UI/UX e.g., mitchellh/cli type Command interface { // Help should return long-form help text that includes // the command-line usage Help() string // Synopsis should return a one-line, short synopsis // of the command. Synopsis() string // Run should run the actual command with the given CLI // instance and command-line arguments. Run(args []string) int }

Slide 30

Slide 30 text

Exit Code Stdin, Stdout, Stderr

Slide 31

Slide 31 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 32

Slide 32 text

Exit Code Stdin, Stdout, Stderr

Slide 33

Slide 33 text

Play with Others Other systems (softwares) may check error without parting the output (e.g., appc/spec) $ actool validate ./image.json $ echo $? 1 # e.g., CI system can detect something wrong and notify

Slide 34

Slide 34 text

Play with Others We can use os.Exit() // Exit causes the current program to exit with // the given status code. // Conventionally, code zero indicates success, // non-zero an error. // The program terminates immediately; deferred functions are // not run. func Exit(code int) { syscall.Exit(code) }

Slide 35

Slide 35 text

Play with Others When something wrong, call os.Exist with non zero number func main() { filePath := args[1] out, err := somethingCool(filepath) if err != nil { fmt.Printf("Error: %s\n", err.Error()) os.Exit(1) } fmt.Printf("Out: %s\n", out) os.Exit(0) }

Slide 36

Slide 36 text

Play with Others We may need defer for some cleaning up func main() { filePath := args[1] out, err := somethingCool(filepath) if err != nil { fmt.Printf("Error: %s\n", err.Error()) os.Exit(1) } defer cleanup() fmt.Printf("Out: %s\n", out) os.Exit(0) }

Slide 37

Slide 37 text

Play with Others But deferred functions are not run if we call os.Exit() // Exit causes the current program to exit with // the given status code. // Conventionally, code zero indicates success, // non-zero an error. // The program terminates immediately; deferred functions are // not run. func Exit(code int) { syscall.Exit(code) }

Slide 38

Slide 38 text

Play with Others Call os.Exit only on main() and create function return exit code func main() { os.Exit(Run(os.Args[1:])) } func Run(args []string) int { filePath := args[0] out, err := somethingCool(filePath) if err != nil { fmt.Printf("Error: %s\n", err.Error()) return 1 } defer cleanup() fmt.Printf("Out: %s\n", out) return 0 }

Slide 39

Slide 39 text

Exit Code Stdin, Stdout, Stderr

Slide 40

Slide 40 text

Exit Code Stdin, Stdout, Stderr

Slide 41

Slide 41 text

Play with Others “ Write programs to handle text streams, because that is a universal interface. - Doug McIlroy func main() { os.Exit(Run(os.Args[1:])) } func Run(args []string) int { filePath := args[0] out, err := somethingCool(filePath) if err != nil { fmt.Fprintf(os.Stderr, "Error: %s\n", err.Error()) return 1 } defer cleanup() fmt.Fprintf(os.Stdout,"Out: %s\n”, out) return 0 }

Slide 42

Slide 42 text

Play with Others “ Write programs to handle text streams, because that is a universal interface. - Doug McIlroy // os.Stdout/os.Stderr is io.Writer // So mostly configurable from other function // flag pacakge flag.SetOutput(os.Stderr) // log package log.SetOutput(os.Stderr)

Slide 43

Slide 43 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 44

Slide 44 text

README.md Usage Man page

Slide 45

Slide 45 text

README.md Usage Man page

Slide 46

Slide 46 text

Helpful Standard flag package output is … $ ghr -h Usage of ghr: -p=0: Parallelization factor -debug=false: Run as debug mode -username=“": Github username -quiet=false: be quieter in some situations -version=false: Print version information and quit

Slide 47

Slide 47 text

Helpful Write by yourself, more clear usage flag.Usage = func() { fmt.Fprint(os.Stderr, helpText) } var helpText = ` Usage: ghr [options] args Command ghr is … Options: -debug Run as Debug mode… `

Slide 48

Slide 48 text

Helpful Go1.5, help out will be a little bit better $ ghr -h Usage of call: -p int Parallelization factor -debug run as debug mode -username string GitHub user name -quiet be quieter in some situations -version Print version information and quit.

Slide 49

Slide 49 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 50

Slide 50 text

json yaml toml hashicorp/hcl

Slide 51

Slide 51 text

NO STRONG OPINION Just think about playing with others Thinks about your team preference

Slide 52

Slide 52 text

USE ONE CENTRAL CONF Keep it in one place

Slide 53

Slide 53 text

Configurable Central one place will be mostly $HOME directory, and you can use user.Current() var defaultCfgName = ".xxxrc" func main() { userInfo, err := user.Current() if err != nil { panic(err) } cfg := filepath.Join(userInfo.HomeDir, defaultCfgName) // … }

Slide 54

Slide 54 text

Configurable It depends on cgo … // src/os/user/lookup_unix.go u := &User{ Uid: strconv.Itoa(int(pwd.pw_uid)), Gid: strconv.Itoa(int(pwd.pw_gid)), Username: C.GoString(pwd.pw_name), Name: C.GoString(pwd.pw_gecos), HomeDir: C.GoString(pwd.pw_dir), }

Slide 55

Slide 55 text

Configurable Provide platform agnostic configuration file, use mitchellh/home-dir import "github.com/mitchellh/go-homedir" var defaultCfgName = ".xxxrc" func main() { home, err := homedir.Dir() if err != nil { panic(err) } cfg := filepath.Join(home, defaultCfgName) // … }

Slide 56

Slide 56 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 57

Slide 57 text

Painless Installation Provide Copy & Paste -able one line command (e.g., on README.md) $ curl -L https://github.com/docker/machine/releases/download/ v0.3.0/docker-machine_darwin-amd64 \ > /usr/local/bin/docker-machine $ chmod +x /usr/local/bin/docker-machine

Slide 58

Slide 58 text

Painless Installation Write homebrew formula, it’s easy class Ghr < Formula homepage "https://github.com/tcnksm/ghr" version 'v0.4.0' url "https://github.com/tcnksm/ghr/releases/download/v0.4.0/ ghr_v0.4.0_darwin_amd64.zip" sha1 “1aa90dde58c3b15dfd1e2f90cbaa317ee4752855” end

Slide 59

Slide 59 text

No content

Slide 60

Slide 60 text

Painless Installation Upload cross-compiled binaries in parallel on Github Releases $ ghr v0.1.0 pkg/ --> Uploading: pkg/0.1.0_SHASUMS --> Uploading: pkg/ghr_0.1.0_darwin_386.zip --> Uploading: pkg/ghr_0.1.0_darwin_amd64.zip --> Uploading: pkg/ghr_0.1.0_linux_386.zip --> Uploading: pkg/ghr_0.1.0_linux_amd64.zip --> Uploading: pkg/ghr_0.1.0_windows_386.zip --> Uploading: pkg/ghr_0.1.0_windows_amd64.zip

Slide 61

Slide 61 text

git push hook compile ghr dev

Slide 62

Slide 62 text

No content

Slide 63

Slide 63 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 64

Slide 64 text

Testing Updating

Slide 65

Slide 65 text

Testing Updating

Slide 66

Slide 66 text

Testing is important for fixing bug and adding new feature Maintainable func main() { os.Exit(Run(os.Args[1:])) } func Run(args []string) int { filePath := args[0] out, err := somethingCool(filePath) if err != nil { fmt.Fprintf(os.Stderr, "Error: %s\n", err.Error()) return 1 } defer cleanup() fmt.Fprintf(os.Stdout,"Out: %s\n”, out) return 0 }

Slide 67

Slide 67 text

os.Exit() os.Args() main() Run() user APIs user os.Stdout os.Stderr [] string int

Slide 68

Slide 68 text

os.Exit() os.Args() main() Run() user APIs user os.Stdout os.Stderr [] string int

Slide 69

Slide 69 text

os.Exit() os.Args() main() Run() user APIs user os.Stdout os.Stderr [] string int

Slide 70

Slide 70 text

Maintainable func TestRun(t *testing.T) { // test console output and status code by argument } Test for console output and status code by arguments

Slide 71

Slide 71 text

os.Exit() os.Args() main() Run() user APIs user os.Stdout os.Stderr [] string int

Slide 72

Slide 72 text

os.Args() os.Stdout os.Stderr main() Run() user [] string io.Writer APIs int os.Exit()

Slide 73

Slide 73 text

[]string bytes.Buﬀer Run() user [] string io.Writer APIs int TestRun()

Slide 74

Slide 74 text

Use io.Writer type cli struct { outWriter, errWriter io.Writer } func (c *cli) Run(args []string) int { file := args[0] out, err := somethingCool(file) if err != nil { fmt.Fprintf(c.errWriter, "Error: %s\n", err.Error()) return 1 } defer cleanup() fmt.Fprintf(c.outWriter,"Out: %s\n", out) return 0 } Maintainable

Slide 75

Slide 75 text

Use io.Writer func main() { cli := &cli{outWriter: os.Stdout, errWriter: os.Stderr} os.Exit(cli.Run(os.Args[1:])) } Maintainable

Slide 76

Slide 76 text

[]string bytes.Buﬀer Run() user [] string io.Writer APIs int TestRun()

Slide 77

Slide 77 text

Use bytes.Buﬀer func TestRun(t *testing.T) { outWriter, errWriter := new(bytes.Buffer), new(bytes.Buffer) cli := &cli{outWriter: outWriter, errWriter: errWriter} args := strings.Split("./tool xxx.txt", " ") status := cli.Run(args) if status != 0 { t.Errorf("expected %d to eq %d", status, 0) } expected := "cool" if !strings.Contains(outWriter.String(), expected) { t.Errorf("expected %q to eq %q", outWriter.String(), expected) } } Maintainable

Slide 78

Slide 78 text

Testing Updating

Slide 79

Slide 79 text

Testing Updating

Slide 80

Slide 80 text

UPDATE IS IMPORTANT More features & more performance (vulnerability…)

Slide 81

Slide 81 text

DIFFICULT TO ENCOURAGE USER Once users install it, they may not update… Same as iOS or Android Application

Slide 82

Slide 82 text

TCNKSM/GO-LATEST Simple way to check version is latest or not

Slide 83

Slide 83 text

Maintainable Encourage user to upgrade to latest version // Simplest way is using tags on GitHub githubTag := &latest.GithubTag{ Owner: "tcnksm", Repository: "ghr", } res, _ := latest.Check(githubTag, "0.1.0") if res.Outdated { fmt.Printf("0.1.0 is not latest, you should upgrade to %s”, res.Current) }

Slide 84

Slide 84 text

Maintainable Encourage user to upgrade to latest version $ ghr --version gar version v0.3.1, build aded5ca Your version is out of date! The latest version is v0.4.0

Slide 85

Slide 85 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 86

Slide 86 text

OK, how to start ?

Slide 87

Slide 87 text

TCNKSM/GCLI Generates the codes and its directory structure you need to start building CLI tool right out of the box. (Formerly `cli-init`, re-wrote everything from scratch)

Slide 88

Slide 88 text

TCNKSM/GCLI Now you can choose your favorite cli framework # Example, todo CLI application which has add, list # and delete command with mitchellh/cli framework, $ gcli new -F mitchellh_cli -c add -c list -c delete todo

Slide 89

Slide 89 text

TCNKSM/GCLI Now you can choose your favorite cli framework $ tree todo ├── CHANGELOG.md ├── README.md ├── cli.go ├── command │ ├── add.go │ ├── add_test.go │ ├── delete.go │ ├── delete_test.go │ ├── list.go │ ├── list_test.go │ └── meta.go ├── commands.go ├── main.go └── version.go

Slide 90

Slide 90 text

Do ONE Thing Well Intuitive UI/UX Play with Others Helpful Configurable Painless Installation Maintainable

Slide 91

Slide 91 text

@deeeet