Building Command Line Tools with Go

Faris Huskovic

 on May 5th, 2021

Updated on June 15th, 2021

9 min read

Options

Go is a great programming language for building command line tools.

The most popular command line package in the ecosystem being spf13’s Cobra.

The standard library is also a great option when you combine the os and flag packages.

You may be asking yourself, which one is right for me?

Choosing the right package

The package you choose should be based on the functionality you’re looking for.

If you’re just building a simple interface for application start up, you may not need something as robust as cobra.

You could probably get away with just using the standard library if all you need is some rudimentary flag parsing.

Now what if you’re in the middle?

What if you know you don’t need half the things cobra offers but you also need something more structured than a single switch statement for evaluating all your operating system arguments?

Enter cdr/cli

cdr/cli is a minimalistic go package for building command line tools.

It’s simple, easy to use, and allows you to quickly put a CLI together.

Let's get a little more familiar with this package by building a port scanner in go.

Project structure

Let's start by initializing our mod file and an idiomatic go application structure.

├── cmd
│   └── port-scanner
|       ├── scan.go
│       ├── root.go
│       └── main.go
├── go.mod
├── go.sum
└── port-scanner

Another common pattern is to keep each command in its own dir under cmd, including that command's subcommands.

You can find an example of that approach in the go standard library.

Our root command will only have one subcommand for our demo so I feel that justifies keeping them in the same directory for the purpose of this demo.

The port-scanner/cmd/port-scanner dir is our entry point.

We can define our root command here.

Root command

port-scanner/cmd/port-scanner/root.go

package main

import (
    "github.com/spf13/pflag"
    "go.coder.com/cli"
)

// We define our command as a struct.
type root struct{}

// Our command struct needs to implement the Command interface as defined by cdr/cli.
// See: https://pkg.go.dev/go.coder.com/cli#Command for more details.
func (r *root) Run(fl *pflag.FlagSet) {
    fl.Usage()
}

// We'll also need to implement a method for returning a command spec to fully satisfy the
// the aforementioned Command interface.
func (r *root) Spec() cli.CommandSpec {
    return cli.CommandSpec{
        Name:  "port-scanner",
        Usage: "[subcommand] [flags]",
        Desc:  "A simple port-scanner.",
    }
}

// We can now attach subcommands to our command struct; implementing ParentCommand as a result as defined by cdr/cli.
// See https://pkg.go.dev/go.coder.com/cli#ParentCommand for more details.
func (r *root) Subcommands() []cli.Command {
    return []cli.Command{
        new(scanCmd),
    }
}

Great! Now that we’ve defined our root command, we can run it out of our main func.

port-scanner/cmd/port-scanner/main.go

package main

import "go.coder.com/cli"

func main() {
    cli.RunRoot(new(root))
}

Cool, let's compile and run our program and see what we have so far.

go build ./cmd/port-scanner && ./port-scanner

Usage: port-scanner [subcommand] [flags]

A great start no doubt, but we’ll need to add some subcommands if we want our port scanner to do anything.

Subcommand

I would normally implement the port scanner under the internal package or the pkg package (depending on whether or not I wanted to publish this as a public package for others to use), but to keep this short and sweet, let's implement the subcommand and the port scanner in the same file.

port-scanner/cmd/port-scanner/scan.go

package main

import (
    "context"
    "log"
    "net"
    "strconv"
    "sync"
    "time"

    "github.com/spf13/pflag"
    "go.coder.com/cli"
    "golang.org/x/xerrors"
)

const (
    wellKnownPorts = 1024
    allPorts       = 65535
)

var timeout = 3 * time.Second

// This time our command struct has a few fields, we can use these to store our flag values.
type scanCmd struct {
    host          string
    shouldScanAll bool
}

// cdr/cli supports subcommand aliases so let's define one in our command spec to provide
// our users with a more succinct input experience.
func (cmd *scanCmd) Spec() cli.CommandSpec {
    return cli.CommandSpec{
        Name:    "scan",
        Usage:   "[flags]",
        Aliases: []string{"s"},
        Desc:    "Scan a host for open ports.",
    }
}

// When adding flags, hang the following method-signature off your command struct to
// satisfy the FlaggedCommand interface as defined by cdr/cli.
// See https://pkg.go.dev/go.coder.com/cli#FlaggedCommand for more details.
func (cmd *scanCmd) RegisterFlags(fl *pflag.FlagSet) {
    fl.StringVar(&cmd.host, "host", "", "host to scan(ip address)")
    fl.BoolVarP(&cmd.shouldScanAll, "all", "a", false, "scan all ports(scans first 1024 if not enabled)")
}

func (cmd *scanCmd) Run(fl *pflag.FlagSet) {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    if cmd.host == "" {
        fl.Usage()
        log.Fatal("host not provided")
    }

    scanner, err := newScanner(cmd.host, cmd.shouldScanAll)
    if err != nil {
        fl.Usage()
        log.Fatalf("failed to initialize port scanner: %s", err)
    }

    log.Printf("scanning %s...", cmd.host)
    start := time.Now()
    openPorts := scanner.scan(ctx)
    log.Printf("scan completed in %s", time.Since(start))

    if len(openPorts) == 0 {
        log.Printf("%q has no open ports", cmd.host)
        return
    }
    log.Printf("found %d open ports", len(openPorts))
    log.Printf("open-ports: %v", openPorts)
}

// Now let's implement our port scanner.
type scanner struct {
    // We're going to want to scan each port concurrently so let's embed
    // a mutex lock into our scanner to make sure we do this in a thread-safe way.
    sync.Mutex
    host      string
    openPorts []int
    scanAll   bool
}

func newScanner(host string, scanAll bool) (*scanner, error) {
    if net.ParseIP(host) == nil {
        return nil, xerrors.Errorf("%q is an invalid ip address", host)
    }

    return &scanner{
        Mutex:   sync.Mutex{},
        host:    host,
        scanAll: scanAll,
    }, nil
}

func (s *scanner) add(port int) {
    // Since we'll be appending to the same slice from different goroutines,
    // let's make sure we're locking and unlocking between writes.
    s.Lock()
    s.openPorts = append(s.openPorts, port)
    s.Unlock()
}

func (s *scanner) scan(ctx context.Context) []int {
    // Let's use a wait group so we can wait for all of our
    // goroutines to exit before returning our results.
    var wg sync.WaitGroup
    for _, port := range portsToScan(s.scanAll) {
        wg.Add(1)
        // Because the value of the loop-variable 'port' changes on every iteration, we'll want
        // to pass a copy of its value into each new goroutine. We don't need to do this with the
        // 'host' variable because it's not a loop-variable and its value never changes.
        go func(p int) {
            defer wg.Done()
            if isOpen(s.host, p) {
                s.add(p)
            }
        }(port)
    }
    wg.Wait()
    return s.openPorts
}

func portsToScan(shouldScanAll bool) []int {
    max := wellKnownPorts
    if shouldScanAll {
        max = allPorts
    }

    var ports []int
    for port := 1; port < max; port++ {
        ports = append(ports, port)
    }
    return ports
}

func isOpen(host string, port int) bool {
    addr := net.JoinHostPort(host, strconv.Itoa(port))
    conn, err := net.DialTimeout("tcp", addr, timeout)
    if err != nil {
        return false
    }
    _ = conn.Close()
    return true
}

Great, now let's re-compile our program and run the root command to see what the output looks like.

Reviewing the command output

go build ./cmd/port-scanner && ./port-scanner

Usage: port-scanner [subcommand] [flags]

Description: A simple port-scanner.

Commands:
        s, scan  - Scan a host for open ports.

So far so good.

Let’s see what the help output for the scan subcommand looks like.

./port-scanner scan --help

Usage: port-scanner scan [flags]

Aliases: s

Description: Scan a host for open ports.

port-scanner scan flags:
-a, --all           scan all ports(scans first 1024 if not enabled)
    --host string   host to scan(ip address)

Beautiful. I think we’re ready to test this thing out.

Running the port scanner

Let's start by opening a new shell and firing up a local python web server.

python -m SimpleHTTPServer 8000 

Serving HTTP on 0.0.0.0 port 8000 ...

Let’s run our port scanner in a different shell, and while we’re at it let's use the subcommand alias we defined for our scan command.

We’ll also want to use our --all flag since our python server is running on port 8000 (which is outside our default port-range).

./port-scanner s --host 127.0.0.1 --all
2021/03/18 21:52:49 scanning 127.0.0.1...
2021/03/18 21:52:50 scan completed in 886.199117ms
2021/03/18 21:52:50 found 10 open ports
2021/03/18 21:52:50 open-ports: [8000]

There is a discrepancy in the output because I’ve intentionally omitted certain ports for security reasons.

I hope you enjoyed this tutorial.

You can find this code on my github.

I encourage you to see what modifications you can make on your own.

More specifically, why don’t you try adding the capability to scan multiple hosts or an entire network.

That’s how simple it is to build command line tools in go using the cdr/cli package.

Hope you found this useful.

Much love,

—Faris