5 Tips for Writing Small CLI Tools in Rust

Rust is a great language to write small command line tools in. While it gives you some tools for common tasks, allows nice abstractions, it also has a type system and approach to API design that lead you to write robust code. Let me show you some techniques to make this a nice experience.

Update (Jan 2018): I published a crate (Rust library) that contains a lot of what this post describes: quicli.

Update (April 2020): Changed failure for anyhow.

Contents

1. Table of contents

Quick CLI argument handling

There are many libraries out there to help you do that. What I've come to enjoy is structopt: It gives you the power to annotate a struct or enum and turn its fields/variants into CLI flags:

This is very concise - but also very powerful! (It uses clap behind the scenes.)

Or:

Error handling

This was updated April 2020.

In many CLI applications, error handling doesn't have to be complicated. All you need is a library like anyhow that let's you bubble up basically all error types and optionally add some context (descriptions) to them.

This looks easy enough, right? There's a lot of ways to enhance the way you deal with errors, for example by writing your own error types. But for quick CLI tools, this is most often not necessary.

By th way, here is what the error output looks like:

Or:

Many small crates

Don't be afraid to depend on a lot of crates. Cargo is really good at allowing you not to care about compiling and updating dependency, so let Cargo, and the Rust community, help you!

For example, I recently wrote a CLI tool with 37 lines of code. This is the first block:

Note from the future (April 2020): Since the introduction of Rust 2018, you don't need to write extern crate anymore. Yay!

Many small helper functions

I tend to write a lot of small functions. Here's an example of such a "small helper function":

Okay, that's a bit underwhelming. How about this one?

It's one level more abstract than the standard library, hides an allocation of a String with unknown length, but… it's really handy.

I know could put the function bodies just inside the main code, but giving these little code blocks names and getting the option of reusing them is really powerful. It also makes the main function a tad more abstract and easier to read (no need to see through all the implementation details). Furthermore (but this tends to not really shine in small CLI apps) it makes things easily unit-testable.

And by the way: In most small CLI tools, performance is not that important. Feel free to prefer .clone() to sprinkling your code with lifetime parameters.

Lots of structs

In my experience, it really pays off to use a lot of structs. Some scenarios:

• Have the choice between using serde_json::Value with a bunch of matches or a struct with #[derive(Deserialize)]? Choose the struct, get performance, nice errors, and documentation about the shape you expect.
• Pass the same 3 parameters to a bunch of functions? Group them in a (tuple) struct, give the group a name, and maybe even turn some of these functions into methods.
• See yourself writing a lot of boilerplate code? See if you can write a struct/enum and use a derive.

Bonus: Logging

And a bonus round: Some logging with loggerv! (It's really simple, but usually suffices for CLI apps. No need to go all in with streaming JSON logs to logstash for now.)

Sweet! Let's run it three time with more of less verbosity!

Conclusion

These were my five tips for writing small CLI applications in Rust (writing nice libraries is another topic). If you have more tips, let me know!

If you want to dig a little deeper, I'd suggest looking at how to multi-platform build Rust binaries releases, how to use clap to get autocompletion for CLI args, and how to write integration test for your CLI apps (upcoming post).