Notes on writing a CLI people keep

I have written a lot of command line tools, and thrown away most of them. The two that people other than me still run share almost nothing technically. What they share is how they behave in the first thirty seconds.

Do the obvious thing with no arguments

Run the tool with nothing after its name and it should either do the thing it is named after, or tell you in four lines what it does. Not a wall of flags. Not an error.

$ cutlass
Building ./site → 41 pages
Uploading to fly.io
Live at https://rowan-notes.fly.dev

Every flag I have ever added was a small admission that the default was not confident enough.

Print what you are about to do

The scariest moment with a new tool is the second between pressing enter and finding out what it touched. Say the destination out loud before you write to it, and say the path afterwards. It costs two lines and it is the difference between a tool people trust and a tool people wrap in a shell script to be safe.

Failure messages are the product

Nobody reads your README. Everybody reads your error. A good one names what happened, what it was trying to do, and the single next move:

No site found in ./site
  cutlass expects an index.html at the root of the folder.
  Point it somewhere else with: cutlass ./public

Three lines. Compare that with a stack trace, which tells the user about your program rather than about their problem.

Be boring about output

• Colour is for two states: fine and not fine. Anything more and it becomes decoration people learn to ignore.
• Detect a pipe and drop the colour, the spinner and the progress bar without being asked.
• Never clear the screen. The scrollback is the only record of what happened.

A CLI is a conversation with someone who is already halfway through a different task. Say the useful thing, then get out of the way.

The part that is actually hard

None of the above is difficult. It is just unglamorous, and it all lands in the last ten percent of the work, after the interesting problem is solved and the tool technically functions. That is exactly where I abandoned the other eleven.