I recently participated in the Handmade Network Visibility Jam and built a tool that I’d been wanting for my own use:

In a nutshell, Escape Artist shows ANSI escape sequences that are normally invisible. It’s kinda like View Source for the terminal; my hope is that it will be useful for anyone working on shells and terminal applications.

Tech Stack

Escape Artist is primarily written in Rust, using Axum to serve up a web UI using Tailwind+Preact. Events get streamed to the front-end over a websocket. I took great pains to keep the front-end simple; nearly all business logic lives in the Rust back-end, there is no front-end build step, and all dependencies are bundled with the application.

Escape Artist compiles down to a single-file 1.8MB executable, and nearly half of that is Tailwind and an embedded font.

Lessons Learned

Parsing escape sequences out of a stream of bytes is remarkably tricky. Thankfully the vte crate does most of the heavy lifting for us.

This minimal approach to web UI was generally pretty nice! I occasionally ran into a bit of trouble wrangling JS libraries that assume everyone is using NPM, React, and a bundler like webpack, but overall it wasn’t too bad.

I ended up needing to roll my own tooltip solution using Floating UI, and… wow. Their introductory tutorial is one of the best I’ve ever seen for a library in any language.

.NET has been taking huge leaps and bounds in the last few years, and not everyone is aware of it! We’re now able to build small fast single-file .NET applications; this is arguably Go’s biggest strength, and now you can do it in C# and F# too.

Meanwhile, the .NET community has been making excellent libraries to make console applications slick, polished, and easy to write.

The conditions seem right for a .NET renaissance of sorts; all the pieces are in place for us to build great CLI-first software. Here are some useful+easy things you can do in .NET today:

Publish Small Zero-Dependency Executables

In .NET 6 it’s easy to build your application as a single file with no external dependencies (even the .NET runtime!). Applications that include their own runtime are called self-contained. Self-contained apps can be trimmed to remove unused code; trimming reduces a Hello World application from about 60MB to 12MB.

Trimming is well-supported by nearly the entire standard library. Ecosystem support varies; if a library makes heavy use of reflection, C++/CLI, or COM interop then it might not work with trimming yet.

The easiest way to build a trimmed self-contained single-file executable is dotnet publish with the args --self-contained=true -p:PublishSingleFile=true -p:PublishTrimmed=true.

dotnet-releaser makes publishing your app a breeze; it can build for multiple platforms+architectures, then publish the resulting artifacts in a GitHub release.

Console UI

Spectre.Console is a great replacement for Console.WriteLine() and friends. Coloring text with Spectre is as simple as:

AnsiConsole.MarkupLine("[blue]Hello[/] [yellow]World![/]");

It can also do much more; if you need to print tables or prompt users for input, Spectre.Console has you covered. But if you need to build a full-blown terminal UI, check out gui.cs.

Running External Processes

The System.Diagnostics.Process APIs built into .NET are clumsy, to say the least. Thankfully we have much better options these days! Here’s how to run git status with the excellent SimpleExec:

var (stdout, stderr) = await RunAsync("git", "status");

For a more powerful solution, check out CliWrap; anything you can do in a Bash script, you can do in CliWrap.

Robin Sloan’s post about “home-cooked” code has been making the rounds, and for good reason. It’s about highly personalized programs; when you build something purely for yourself or a small audience, it’s more like home cooking than industrial production. I really love the analogy, and it’s inspired me to write about one of my own “home-cooked” tools: wat.

The Problem

I spend a lot of my day in a terminal, and command line interfaces have notoriously poor discoverability. It’s easy to remember the handful of commands+flags you use on a regular basis; it’s much harder to remember the ones you only use a couple times a year. So, like many people, I used to spend a lot of time digging through man pages when 1) I know what I want to accomplish 2) I can’t remember the exact CLI syntax to make it happen.

Unfortunately, man pages usually aren’t designed for this. The average man page is more like a lengthy novel than Cliff’s Notes; it’s thorough+exhaustive documentation when I just want a quick reference.

There are a few excellent projects that provide succinct documentation for *nix commands: tldr and cht.sh are my favourites. But they don’t provide good facilities for adding personalized documentation of my own; that’s where wat comes in.

What Wat Does

wat started out as a simple wrapper around tldr and cht.sh. The two provide similar content, but they do so in different ways; tldr is installed locally, cht.sh is usually accessed through a dead-simple web interface: curl cht.sh/command. The first iteration of wat was just a simple fish function that would call tldr if it’s installed, and otherwise fall back on cht.sh.

These days, wat is written in Python and it’s a tiny bit more sophisticated: it also displays custom Markdown notes which are synced across all my machines using Git.

Say I want to get some information about a video file, but I can’t remember the exact ffprobe syntax. I just type wat ffprobe in my terminal:

This returns a handy tldr/cht.sh summary and it renders the contents of ~/notes/ffprobe.md if it exists. In this case, it looks like I got annoyed enough by ffprobe to write down a note for the -hide_banner flag.

I’ve been maintaining command line notes for a long time, in various tools that just happened to be at hand: OneNote, Notes.app, Markdown in a repo… but wat lets me organize that information better, and view it inline with excellent community-provided documentation.