CLI on

Lesson 8: Packaging and Distributing — GoReleaser, Homebrew, and getting your tool to users

Thu, 05 Jun 2025 00:00:00 +0000

Building a great CLI tool is half the job. The other half is getting it to users without making them compile it from source, navigate a GitHub releases page manually, or run a curl-pipe-to-bash script from an unverified URL. Distribution is where many Go projects stop short: the binary exists, the README says go install, and that is considered “distributed.”

go install is fine for Go developers. It is not acceptable for operators, system administrators, and end users who reasonably expect brew install or apt install. GoReleaser closes this gap by automating the full release pipeline — cross-compiled binaries, checksums, GitHub releases, Homebrew formulas, Debian packages, Docker images — from a single configuration file and one git push --tags.

Lesson 7: Build Flags and ldflags — Inject version info at compile time

Sat, 05 Apr 2025 00:00:00 +0000

A CLI tool that cannot tell you what version it is running is a frustrating tool to operate. When something breaks, the first question is “which version?” Without a proper answer, debugging becomes archaeology. The good news is that Go’s build system provides two mechanisms for injecting metadata at compile time — ldflags for injecting variable values from the shell, and build constraints for including or excluding code based on the build context — and both are straightforward once you understand their syntax.

Lesson 6: Embedding Assets — embed.FS puts files inside your binary

Wed, 05 Feb 2025 00:00:00 +0000

Before Go 1.16, embedding static assets in a Go binary required either a code generation tool that converted files to byte arrays, a third-party library like packr or statik, or shipping the files alongside the binary and reading them from disk at runtime. Each approach had real costs: generated code bloated repositories, third-party tools had to be installed separately, and shipping separate files broke the “single binary” distribution story.

The //go:embed directive in Go 1.16 solved this cleanly. Files, directories, and whole asset trees can be embedded directly into the binary with a single comment and a variable declaration. Templates, SQL migrations, web assets, default configs — everything your binary needs can travel with it.

Lesson 5: Cross-Compilation — Build for Linux from your Mac in one command

Tue, 10 Dec 2024 00:00:00 +0000

One of Go’s most practical superpowers is that cross-compilation is a first-class feature, not an afterthought. Two environment variables — GOOS and GOARCH — are all you need to produce a Linux binary from macOS, a Windows executable from Linux, or an ARM binary from an x86 machine. No Docker containers required, no cross-compilation toolchain setup, no linker flags hunting. Just GOOS=linux GOARCH=amd64 go build and you have a production-ready binary for the target platform.

Lesson 4: Signal Handling — Catch SIGTERM or lose your work

Wed, 30 Oct 2024 00:00:00 +0000

Most CLI tools work perfectly on the happy path and fail silently on the unhappy one. The user presses Ctrl-C, the OS sends SIGINT, and the process dies immediately — leaving a temp file half-written, a database connection open, or a progress bar frozen mid-operation. The problem is invisible because most of the time nobody looks at what gets left behind. Until a deployment script depends on that temp file being complete, or a database hits its connection limit, or a batch job loses six hours of progress because the container was terminated between checkpoints.

Lesson 10: Testing CLI Applications — End-to-end CLI tests

Sun, 22 Sep 2024 12:10:00 +0000

I shipped a CLI tool with 100% unit test coverage on the core logic. Users immediately found three bugs. The argument parser accepted --port but the value wasn’t being passed to the server. The --json flag produced output that wasn’t valid JSON because of a stray debug print. And --help showed the wrong default for --timeout. None of these bugs lived in the “core logic.” They lived in the glue between clap, the output formatter, and the actual binary. Unit tests didn’t catch them because unit tests don’t run the actual binary.

Lesson 9: Building TUIs with ratatui — Terminal user interfaces

Thu, 19 Sep 2024 07:55:00 +0000

I was monitoring a deployment through five separate terminal windows — one for logs, one for metrics, one for the deployment status, one for the database, and one running htop. Alt-tabbing between them like a madman. Then a colleague showed me their custom TUI dashboard that combined all five views into a single terminal screen, with tabs and live-updating graphs. It was written in Rust with ratatui. I rebuilt it that weekend.

Lesson 8: Distribution — Static binaries, cargo-dist, Homebrew

Mon, 16 Sep 2024 19:40:00 +0000

I built a CLI tool that three teams at work used daily. It lived in a shared directory on an NFS mount. Every time I pushed an update, I’d post in Slack: “new version in /shared/tools, please copy it to your PATH.” Half the team was running a version from three months ago because they forgot. The other half had four copies scattered across their home directories. Distribution matters. If installing your tool is harder than brew install myapp, most people won’t bother.

Lesson 7: Cross-Compilation for Linux, Mac, Windows — Build once, run anywhere

Sat, 14 Sep 2024 10:25:00 +0000

First time I tried to cross-compile a Rust binary from my Mac to Linux, I ran cargo build --target x86_64-unknown-linux-gnu and got hit with a wall of linker errors. Missing cc, wrong libc, something about crt1.o. It felt like the “build once, run anywhere” promise was a lie. It wasn’t — I just didn’t understand how Rust’s compilation model interacts with system libraries. Once that clicked, cross-compilation became routine.

How Rust Compilation Works

Rust compiles to LLVM IR, then LLVM generates machine code for the target architecture. That part works across platforms — LLVM knows how to emit x86_64, aarch64, arm, riscv, wasm, and more. The problem is the linker.

Lesson 3: File I/O Patterns — Read, write, stream without loading everything into memory

Thu, 12 Sep 2024 00:00:00 +0000

CLI tools spend most of their life doing file I/O. Reading config files, processing log dumps, writing output, transforming data from stdin to stdout — it all comes down to bytes moving through your program. The difference between a CLI tool that handles 100MB files gracefully and one that runs out of memory on large inputs is almost always whether you read everything into memory or stream it.

Go’s standard library gives you everything you need to stream data efficiently. The key is knowing which functions to reach for and which ones to avoid when the input is large or unknown in size.

Lesson 6: Subcommands and Complex CLI Structures — git-style interfaces

Wed, 11 Sep 2024 13:50:00 +0000

Every tool starts as mytool --flag input.txt. Then someone asks for a second mode. Then a third. Before you know it, you have mytool --mode=convert --input foo --output bar and mytool --mode=validate --strict --input foo and users are scrolling through --help trying to find the three flags that matter for their use case. The answer is subcommands. git commit, docker build, cargo test — separate commands with separate flags, unified under one binary.

Lesson 5: Signal Handling and Graceful Shutdown — Clean exits

Mon, 09 Sep 2024 09:17:00 +0000

I had a CLI tool that converted video files. Big ones — 10, 20 gigabytes each. The conversion created a temp file, wrote the converted output there, then renamed it to the final destination. Hit Ctrl+C at the wrong moment and you’d get a half-written 15GB temp file sitting on disk. Users ran out of disk space without knowing why. All because I never handled signals properly.

What Happens When You Press Ctrl+C

When you press Ctrl+C in a terminal, the kernel sends SIGINT (signal interrupt) to the foreground process group. By default, this kills your program immediately. No destructors run. No Drop implementations execute. Temporary files stay on disk. Database connections aren’t closed. Partial writes aren’t rolled back.

Lesson 4: Colored Output and Progress Bars — UX for the terminal

Sat, 07 Sep 2024 16:33:00 +0000

I used to think terminal output was either plain text or ANSI escape code soup. Then I looked at how tools like cargo, ripgrep, and bat handle their output — color used purposefully to draw the eye, progress bars that give you actual information, spinners that tell you something is happening. Good terminal UX isn’t about making things pretty. It’s about making information scannable.

Raw ANSI Escape Codes

Before using any crate, you should understand what’s actually happening. Terminal colors are just special byte sequences embedded in the output stream:

Lesson 3: Configuration Files and Environment Variables — Config that scales

Thu, 05 Sep 2024 11:08:00 +0000

I shipped a CLI tool with 23 flags once. Twenty-three. The --help output scrolled past two terminal screens. Users hated it, nobody could remember the flags, and every deployment script was a wall of backslash-continued command lines. That’s when I learned: if your tool has more than about eight flags, you need a configuration file.

The Configuration Hierarchy

Every serious CLI tool follows the same precedence order:

Command-line flags (highest priority)
Environment variables
Project-local config file (.myapp.toml in the current directory)
User config file (~/.config/myapp/config.toml)
System config file (/etc/myapp/config.toml)
Compiled-in defaults (lowest priority)

Each layer overrides the one below it. This lets users set defaults in their home directory, override them per-project, and override those on a per-invocation basis with flags. kubectl, git, docker — they all work this way.

Lesson 2: stdin, stdout, stderr — I/O patterns

Tue, 03 Sep 2024 08:45:00 +0000

A coworker once asked me to review a Rust CLI they’d written. It read a CSV file, transformed some columns, and wrote the result. Worked perfectly — until someone piped in a 2GB file. The tool ate 4GB of RAM, hung for thirty seconds, then crashed. They were reading the entire file into a String before processing a single line. Classic.

Why I/O Is Harder Than It Looks

Unix tools work because of a simple contract: read from stdin, write to stdout, errors to stderr. cat file | grep pattern | sort | uniq -c. Each program does one thing. They compose through pipes. It’s beautiful when it works.

Lesson 1: clap — Argument parsing done right

Sun, 01 Sep 2024 14:22:00 +0000

I’ve written argument parsers by hand in four different languages. Every single time, I ended up with a tangled mess of string matching, edge cases around flags that take optional values, and help text that drifted out of sync with reality within a week. Then I found clap.

The Problem With Rolling Your Own

Parsing command-line arguments seems simple. You grab std::env::args(), maybe split on =, handle some --flag and -f cases. Works great until someone passes --output= with no value. Or uses -vvv for triple verbosity. Or expects --help to just work. Or wants --color=always|never|auto. Suddenly your 40-line parser is 400 lines of spaghetti.

Lesson 2: Config and Env Handling — Viper, envconfig, or just os.Getenv?

Mon, 05 Aug 2024 00:00:00 +0000

Configuration is one of those problems that looks trivial until it is not. A single environment variable is three lines of code. A configuration file with overridable environment variables, sensible defaults, validation, and reload-on-signal is a project in itself. Knowing when to use each approach — raw os.Getenv, struct-based env decoding, or a full configuration library like Viper — is more about understanding the tradeoffs than about which library is “best.”

Lesson 1: Building CLIs with Cobra — From main.go to production CLI

Sat, 22 Jun 2024 00:00:00 +0000

Every Go project that grows into something useful eventually needs a command-line interface. Maybe it starts as a quick main.go with os.Args[1] checks and a switch statement. That works until you need subcommands, flags, help text, shell completion, and version information — and suddenly you are maintaining a hand-rolled argument parser that nobody wants to touch. Cobra is the standard library-grade solution to this problem, and learning to structure a Cobra application properly saves you from rewriting it twice.