Rust CLI & Tooling on Atharva Pandey

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 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.