A First Go CLI: Tooling, Debugging, and Fast Iteration

Preamble

The topic plan nudged a Go refresh. This post treats that refresh as a deep dive: a minimal CLI you can run and test, the debugging story end to end, the static tools that catch mistakes before runtime, and notebook-shaped workflows that approximate Jupyter’s “try a cell, see output” loop.

Why Go beside Python and Java

Static binaries simplify distribution—no interpreter path dance on jump boxes. Fast compile loops reward small tools that would feel heavy as Java JARs or as Python scripts missing venv discipline. Go is not a replacement for either language in my stack; it is a specialist for ops-shaped utilities.

Modules and versioning

go mod init, go get at semantic versions, and committed go.sum mirror the pinning instinct from pip-tools months. The ecosystem differs, but the reproducibility goal does not.

From an empty directory:

go mod init example.com/helloctl

Dependencies are ordinary import paths; go get records them in go.mod and go.sum. go mod tidy prunes unused modules—run it before commits when the graph has wandered.

A first CLI: flag, context, and a pinch of structure

For a single binary with a few options, the standard library flag package is enough. Reserve cobra when subcommands and shell completion become the main complexity.

package main

import (
	"context"
	"flag"
	"fmt"
	"os"
	"time"
)

func main() {
	verbose := flag.Bool("v", false, "verbose logging")
	timeout := flag.Duration("timeout", 5*time.Second, "overall timeout")
	flag.Parse()

	if flag.NArg() < 1 {
		fmt.Fprintln(os.Stderr, "usage: helloctl [-v] [-timeout=5s] <name>")
		os.Exit(2)
	}
	name := flag.Arg(0)

	ctx, cancel := context.WithTimeout(context.Background(), *timeout)
	defer cancel()

	if *verbose {
		fmt.Fprintf(os.Stderr, "starting greet for %q (timeout=%v)\n", name, *timeout)
	}

	select {
	case <-time.After(50 * time.Millisecond):
		fmt.Printf("hello, %s\n", name)
	case <-ctx.Done():
		fmt.Fprintln(os.Stderr, "timeout:", ctx.Err())
		os.Exit(1)
	}
}

context is idiomatic for cancellation and deadlines—the same ideas show up in HTTP clients, gRPC, and worker pools. flag keeps the CLI surface small; integration tests can call flag.CommandLine or factor parsing into a function that takes []string if you outgrow main.

Debugging Go: what to reach for first

Delve (dlv)

Delve is the de facto source-level debugger for Go. It understands goroutines, stack traces, and optimized binaries better than a generic C debugger.

Typical flows:

# Debug the current package's tests
dlv test ./...

# Debug a binary you are about to build
dlv debug ./cmd/helloctl -- -v world

In VS Code or Cursor, install the Go extension (which uses gopls and Delve under the hood). Breakpoints, step in/over/out, locals, and goroutine lists map cleanly to Python or Java IDE debugging—except values are often copies (structs, small strings) and you should remember receiver and pointer semantics when “the variable didn’t change.”

When the process panics

Uncaught panics print a stack trace. Set GOTRACEBACK=all (or crash on Unix) when you need every goroutine in the dump. For servers, log panics at process boundaries and prefer recover only at top-level handlers where you can return a 500 or restart a unit of work—not deep inside libraries.

CPU, memory, and execution traces: pprof

The runtime/pprof and net/http/pprof packages expose profiles you can open with go tool pprof. For a quick local check on a CLI, you can instrument main with runtime/pprof and write a CPU profile to a file, or run tests with -cpuprofile / -memprofile.

Execution traces (go tool trace) answer “who blocked whom?”—valuable when goroutines interact with channels and select.

Data races: -race

Build or test with -race:

go test -race ./...

The race detector instruments memory access and reports unsynchronized reads/writes. It is slow and not for production binaries, but it is the fastest way to learn whether your first concurrent code is actually safe.

go vet and static analysis

go vet catches common mistakes (printf format verbs, wrong struct tags, unreachable code). Treat staticcheck and golangci-lint (a meta-linter) as the next layer: unused code, suspicious constructs, and project-specific rules.

Tooling map (the short version)

go generate wires code generation (stringer, mocks, protobuf) into repeatable commands—useful once CLIs grow beyond hand-written flags.

“Like Jupyter” for Go: fast onboarding and iteration

Go is compiled; there is no first-class REPL in the toolchain. You still have notebook-shaped and scratch workflows:

1. Gonb (Go notebooks) — A Jupyter kernel for Go (gonb) gives cells, rich output, and incremental runs in a familiar notebook UI. It is the closest analogue to fleshing out ideas in Jupyter while staying in Go syntax and the standard library.
2. gophernotes — An older Jupyter kernel; some setups still use it, but gonb is the more actively developed story for recent Go notebooks.
3. go run on a scratch file — A scratch.go with package main and a main() is the zero-dependency loop: edit, run go run ., repeat. Compile time is usually sub-second for small programs—often faster than spinning a notebook kernel.
4. The Go Playground — go.dev/play for shareable snippets; fine for algorithms, useless for filesystem or network I/O.
5. Editor scratch — VS Code “Go Playground” style extensions or a temporary module in /tmp with go mod init scratch duplicates the notebook mental model without Jupyter.

For learning, pick one notebook path (gonb) or a tight go run habit; both beat reading about defer without executing it.

Cross-training for 2025

2025’s concurrency posts compare BEAM and Tokio. Go’s goroutines are another point in the design space—reading one runtime well makes the next easier. The habit is measurement, not syntax tourism. After a working CLI, run go test -race, capture a CPU profile on a hot path once, and you have already exercised the debugger mindset in Go’s terms.

Conclusion

Comfort with multiple runtimes sharpens comparisons. This slice—modules, a flag-driven CLI, Delve, pprof, -race, and a notebook or scratch loop—covers most of what you need to learn Go by doing without pretending it is Python. Embedded firmware (microcontrollers, pins, watchdogs) is a different concurrency lesson—useful later, but outside this Go-focused path.