behsoh
tools

Writing a Small Command-Line Tool

A tiny program that does one job from the terminal is one of the best early projects. It is finished quickly, it is useful to you, and it teaches conventions that every larger tool relies on.

Why start here

A command-line interface is a program you run by typing its name and some arguments. There is no window to design, no buttons to arrange, and no server to keep running. That leaves you free to concentrate on the logic, and it means your first finished project can be something you use every week: renaming a batch of files, counting words in notes, converting one text format to another.

Pick one job

The oldest advice about such tools is that each should do one thing well. Resist adding a second feature until the first is solid. A tool that counts lines should not also send email. Narrow tools are easier to write, easier to test, and easier to combine with other tools, which is where the terminal gets its power.

Arguments, options, and help

Users give instructions to your tool in two ways. Positional arguments are the things it works on, such as file names. Options, also called flags, change how it behaves, and by convention start with one or two dashes. Almost every language has a standard library for parsing these; use it rather than splitting the text yourself. The library will handle awkward cases and, as a bonus, will generate a help message.

That help message matters. A tool should print a short usage summary when asked with a help option, and when called incorrectly. Write it as if for someone who has never seen the program, which will be true of you after a few months away from it.

Three streams

Every command-line program is connected to three standard streams: standard input, standard output, and standard error. The convention is simple and worth following strictly. Results go to standard output. Messages for the human, such as warnings, progress, and errors, go to standard error. If you mix them, anyone who tries to save your tool's results to a file will find warnings scattered through the data.

Reading from standard input when no file is named is a small courtesy that makes your tool far more flexible, because it can then receive the output of another program directly.

Exit codes are the other output

When a program ends, it hands a small number back to whatever started it. This is the exit status. By long convention, zero means success and anything else means some kind of failure. People rarely look at this number, but scripts depend on it: a script that runs your tool as one step decides whether to continue based on that value. If your tool hits an error, print a message to standard error and exit with a non-zero status. Exiting with zero after a failure is a quiet way of lying to every script that trusts you.

Fail clearly

Good error messages say what went wrong, with which input, and if possible what to do about it. "Error" is useless. "Cannot read notes.txt: file does not exist" lets the user fix the problem without opening your source code. Catch the failures you can foresee, such as a missing file, an unreadable folder, or an empty input, and write a plain sentence for each.

  • One job, described in one sentence.
  • Parse arguments with the standard library.
  • Results to standard output, messages to standard error.
  • Zero on success, non-zero on failure.
  • Error messages that name the input and the reason.

Be careful with anything destructive

If your tool deletes, overwrites, or renames files, give it a way to show what it would do without doing it. This is commonly called a dry run. Make the safe behaviour the default where you can, and require an explicit option for the dangerous one. You will be grateful the first time you run the tool in the wrong folder.

Test it the way it is used

Keep a small folder of sample inputs and the outputs you expect. After each change, run the tool on the samples and compare. Include the awkward cases: an empty file, a file with one line, a name with spaces in it. This takes minutes to set up and catches most of the mistakes that small tools suffer from.

Leave a note for the next reader

Finish with a short file beside the code that says what the tool does, how to run it, and one example of input and output. That file, the help message, and clear error text together are the whole user interface of a command-line tool. They are worth as much care as the logic.

Working rule: if someone can use your tool correctly from its help text alone, and a script can trust its exit status, the tool is finished.

Last revised 2026-11-20 · Wendell Arkwright