Faris Huskovic

Backend Go Developer

<h2>Options</h2>

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

The most popular command line package in the ecosystem being <a href="https://github.com/spf13/cobra">spf13’s Cobra</a>.

The standard library is also a great option when you combine the <a href="https://golang.org/pkg/os/"><code>os</code></a> and <a href="https://golang.org/pkg/flag/"><code>flag</code></a> packages.

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

<h2>Choosing the right package</h2>

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 <a href="https://github.com/spf13/cobra">cobra</a>.

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 <a href="https://github.com/spf13/cobra">cobra</a> offers but you also need something more structured than a <a href="https://gobyexample.com/command-line-subcommands">single switch statement</a> for evaluating all your operating system arguments?

<h2>Enter cdr/cli</h2>

<a href="https://github.com/cdr/cli">cdr/cli</a> 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&#39;s get a little more familiar with this package by building a port scanner in go.

<h2>Project structure</h2>

Let&#39;s start by initializing our <code>mod</code> file and an <a href="https://github.com/golang-standards/project-layout">idiomatic go application structure</a>.

<pre><code>├── cmd
│ └── port-scanner
| ├── scan.go
│ ├── root.go
│ └── main.go
├── go.mod
├── go.sum
└── port-scanner
</code></pre>

Another common pattern is to keep each command in its own dir under <code>cmd</code>, including that command&#39;s subcommands.

You can find an example of that approach in the <a href="https://github.com/golang/go/tree/master/src/cmd">go standard library</a>.

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 <code>port-scanner/cmd/port-scanner</code> dir is our entry point.

We can define our root command here.

<h2>Root command</h2>

<code>port-scanner/cmd/port-scanner/root.go</code>

<pre><code>package main

import (
 &quot;github.com/spf13/pflag&quot;
 &quot;go.coder.com/cli&quot;
)

// 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&#39;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: &quot;port-scanner&quot;,
 Usage: &quot;[subcommand] [flags]&quot;,
 Desc: &quot;A simple port-scanner.&quot;,
 }
}

// 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),
 }
}
</code></pre>

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

<code>port-scanner/cmd/port-scanner/main.go</code>

<pre><code>package main

import &quot;go.coder.com/cli&quot;

func main() {
 cli.RunRoot(new(root))
}
</code></pre>

Cool, let&#39;s compile and run our program and see what we have so far.

<pre><code>go build ./cmd/port-scanner &amp;&amp; ./port-scanner

Usage: port-scanner [subcommand] [flags]
</code></pre>

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

<h2>Subcommand</h2>

I would normally implement the port scanner under the <code>internal</code> package or the <code>pkg</code> 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&#39;s implement the subcommand and the port scanner in the same file.

<code>port-scanner/cmd/port-scanner/scan.go</code>

<pre><code>package main

import (
 &quot;context&quot;
 &quot;log&quot;
 &quot;net&quot;
 &quot;strconv&quot;
 &quot;sync&quot;
 &quot;time&quot;

 &quot;github.com/spf13/pflag&quot;
 &quot;go.coder.com/cli&quot;
 &quot;golang.org/x/xerrors&quot;
)

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&#39;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: &quot;scan&quot;,
 Usage: &quot;[flags]&quot;,
 Aliases: []string{&quot;s&quot;},
 Desc: &quot;Scan a host for open ports.&quot;,
 }
}

// 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(&amp;cmd.host, &quot;host&quot;, &quot;&quot;, &quot;host to scan(ip address)&quot;)
 fl.BoolVarP(&amp;cmd.shouldScanAll, &quot;all&quot;, &quot;a&quot;, false, &quot;scan all ports(scans first 1024 if not enabled)&quot;)
}

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

 if cmd.host == &quot;&quot; {
 fl.Usage()
 log.Fatal(&quot;host not provided&quot;)
 }

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

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

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

// Now let&#39;s implement our port scanner.
type scanner struct {
 // We&#39;re going to want to scan each port concurrently so let&#39;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(&quot;%q is an invalid ip address&quot;, host)
 }

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

func (s *scanner) add(port int) {
 // Since we&#39;ll be appending to the same slice from different goroutines,
 // let&#39;s make sure we&#39;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&#39;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 &#39;port&#39; changes on every iteration, we&#39;ll want
 // to pass a copy of its value into each new goroutine. We don&#39;t need to do this with the
 // &#39;host&#39; variable because it&#39;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 &lt; 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(&quot;tcp&quot;, addr, timeout)
 if err != nil {
 return false
 }
 _ = conn.Close()
 return true
}
</code></pre>

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

<h2>Reviewing the command output</h2>

<pre><code>go build ./cmd/port-scanner &amp;&amp; ./port-scanner

Usage: port-scanner [subcommand] [flags]

Description: A simple port-scanner.

Commands:
 s, scan - Scan a host for open ports.
</code></pre>

So far so good.

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

<pre><code>./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)
</code></pre>

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

<h2>Running the port scanner</h2>

Let&#39;s start by opening a new shell and firing up a local python web server.

<pre><code>python -m SimpleHTTPServer 8000 

Serving HTTP on 0.0.0.0 port 8000 ...
</code></pre>

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

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

<pre><code>./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]
</code></pre>

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 <a href="https://github.com/fuskovic/port-scanner">github</a>.

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 <a href="https://github.com/cdr/cli">cdr/cli</a> package.

Hope you found this useful.

Much love,

—Faris

<hr />
Note: This content originally appeared on <a href="https://www.farishuskovic.dev/">Faris&#39;s personal blog</a> and is reprinted here with his permission.

Learn how to use the coder/cli package to create a command line port scanner with this tutorial.

Building Command Line Tools with Go

Hey! I work on Coder's background processes, workspace build operations, and maintain our open source command-line packages and tools.

AI-native Development

Secure Environments for 2,500+ Developers

Faris Huskovic

Explore the latest from Faris

Building Command Line Tools with Go

Related content

Using Claude Code with Coder Workspaces

Introducing Coder Agents

Self-Hosted Doesn’t Always Mean What It Implies