Cobra vs clap-rs for a Homelab CLI: When the Flag Parser Becomes Half the Project

The first useful version of my homelab CLI was a bash file with three flags and a case statement. The second version needed subcommands: backup, restore, wake, cert. The third version needed shared persistent flags, a config file, and help text I would not be ashamed to paste into a family chat. That is when the flag parser became half the project. Not because parsing is hard. Because the parser is where you decide whether this thing is a script with a costume, or a tool you will still run in a year.

If you write Go, the costume is usually Cobra. If you write Rust, it is usually clap. The language fork underneath is still Rust versus Go for CLI tools. Both will give you tool backup --dry-run and a --help tree. They cost different kinds of time. Homelab CLIs are not Kubernetes CLIs. You do not have a docs team. You have a Saturday and a box that must not eat the NAS because you inverted a boolean. The crate you pick should shrink that Saturday, not give it a mascot.

What Cobra is selling

Cobra is a command graph. You add a root, you add children, you attach persistent flags, you optionally marry Viper for config. It looks like kubectl because kubectl is the cultural parent. For a homelab tool that already lives in a Go repo — maybe next to a small HTTP daemon — Cobra is the path of least social resistance. Anyone who has read a Go ops tool will find the files.

The cost is ceremony. A new subcommand is a file, an init(), a Run or RunE, flag registration that does not live next to the struct you wish you had. You can write Cobra in a tight style. Most examples do not. Homelab tools accrete examples. Six months later you have three ways to read an environment variable and a persistent flag that is ignored on the one command you actually use.

Cobra is also slow to compile in the way Go is not, until you import the rest of the universe. The parser is not the problem. The problem is that Cobra invites a “real CLI” architecture for a binary whose entire job is to wrap restic and a wake-on-LAN packet. I have seen more time spent on cobra.Command wiring than on the backup path. That is the failure mode in the title.

What clap is selling

clap (the Rust crate, the one everyone means when they say clap-rs) wants your CLI to be a type. Derive a struct, annotate fields, get help, env, defaults, and subcommands from the shape of the data. The happy path is short. The types make illegal flag combinations harder to represent, which matters when --restore and --forget should not travel together.

The cost is Rust. If the homelab CLI is your only Rust program, you will spend the Saturday on the toolchain, not on clap. If you already write Rust for small daemons, clap is cheaper than Cobra is in Go, because you do less copying of strings into global variables. Compile times are the joke everyone tells. For a binary this size they are a coffee, not a culture.

clap’s builder API still exists if derive gets in your way. Homelab tools rarely need that escape hatch on day one. They need it on day thirty, when you want a hidden flag or a deprecated alias. Both crates can do aliases. clap makes the common case smaller. Cobra makes the kubectl-shaped case familiar.

When the parser eats the project

Half the project is not a compliment. It happens when you add completion generation, man pages, a config search path, and nested subcommands for every shell script you used to run by name. Cobra is especially good at that accretion because the ecosystem assumes you wanted a platform. clap will also let you grow a tree that needs a map.

I now use a rule. If the tool has one verb and a handful of options, I do not take either crate’s full religion. Go gets flag or a tiny parse. Rust gets a single derive struct. If the tool has a verb family that humans must discover — backup, restore, status — I pick Cobra or clap and I stop. No plugin system. No REPL. Completions if I have twenty minutes, not if I have an architecture feeling.

The dangerous feeling is “this might be useful to other people.” That is how a wake-on-LAN helper grows a factory of commands. Ship the three commands you run. Leave the rest in the README as curl one-liners.

Completions, config, and the family computer

Both ecosystems can emit shell completions. Cobra’s are battle-tested because of Kubernetes muscle memory. clap’s are fine. For a homelab CLI, completions matter more than pretty help if you type the tool daily. They matter less than a default that will not format a disk. I generate completions after the flags are stable. Generating them first is how you freeze a bad name.

Config files are where Cobra-plus-Viper becomes a second project. YAML in ~/.config/labctl/config.yaml feels professional. It also means the CLI now has a merge order: flag, env, file, default. You will get that wrong. clap can read env and defaults on the struct and skip the file. I skip the file until the same flag appears in four scripts. Then I add a file and I write a test for the merge, even if the test is a shell script that prints the effective config.

On a family computer, the CLI might be run by someone who did not write it. Help text is the UI. clap’s derive help is consistent. Cobra help is consistent if you are disciplined about Short and Long. Neither saves you from a flag named --force that means two things.

Language gravity beats crate features

The honest reason to pick Cobra is that the rest of the homelab glue is Go: Prometheus exporters, a little API, maybe Caddy’s friend in the same module. The honest reason to pick clap is that the rest is Rust: a tiny daemon, a parser, a love of types. Switching languages so the flag crate is nicer is how you get two toolchains and one unfinished binary.

If you are choosing a language for the CLI, I pick Go when the work is wrapping other programs and talking HTTP. I pick Rust when the work is parsing, packing, or staying resident as a small service that also has a CLI. clap plus a daemon in one crate is a nice shape. Cobra plus a daemon in one module is also a nice shape. The crate is not the strategy. The strategy is not starting a third language because a blog used clap in a title.

Errors and dry runs

Homelab CLIs should fail loud and do nothing when confused. Cobra’s RunE makes that easy if you use it. Plenty of examples use Run and log. clap’s derive plus Result in main is the Rust default if you do not fight it. I care more about a global --dry-run that every subcommand honors than about which crate printed the usage.

I implement dry-run as a context value, not as a flag each command re-declares and forgets. Cobra persistent flags help. clap’s flatten or a shared args struct helps. If you cannot point to the one place dry-run is read, the parser already ate the project.

The decision I make on a new tool

If I am already in Go and I need subcommands, I use Cobra and I keep the graph shallow. One level of children. Persistent flags for config path, verbose, dry-run. No Viper until I am annoyed. If I am already in Rust, I use clap derive and the same shallow graph. If I am in bash and it still fits, I stay in bash. The flag crate is not a personality.

I revisit the choice when help text is a lie or when adding a command takes longer than writing the command. That is the signal the parser became half the project. The fix is usually deletion, not a rewrite in the other language. Rewrites feel like progress. They are how a wake-on-LAN tool misses another year of use.

Distribution is the last place people waste a weekend. Go gives you a single static-ish binary with little drama. Rust does too if you stay away from glibc surprises on an old NAS. Neither crate changes that. If you cannot copy one file onto the box and run it, the flag parser was never your blocker.

Cobra and clap are both good. Homelab CLIs fail when the author uses them to practice building kubectl. Build the three verbs. Make dry-run real. Generate completions last. Let the parser be a thin skin, not the hobby. The NAS does not care which crate printed --help. It cares whether restore did what the flag claimed.