Guidelines for creating your own CLI tool

Published in

Jit Team

4 min readSep 19, 2022

Offering a great CLI experience is more about making your commands work well and follow best practices, rather than reinventing the concept of a CLI. The best way to learn about building great CLIs is to study other CLIs that have a great reputation and analyze what makes them great.

The CLI ecosystem is vast and it can be hard to find the perfect match for your needs. There are a lot of different choices out there. Here are some of the best CLI tools and libraries:

Python: argparse, click , rich-click (rich)
Node: oclif (Heroku, Salesforce, Shopify), Inquirer
Go: cobra (Kubernetes, Helm, GitHub CLI, Hugo)
C++: Boost::Program Options, gflags, CLI11
Rust: clap
React: ink (Gatsby)
.Net: command-line-api

Remember: your commands should be easy to understand and use, your output should be easy to read, and your documentation should be easy to follow. If you can follow these simple guidelines, you’ll be well on your way to creating a great CLI experience.

Example of Git’s CLI

The git CLI is great because the commands are easy to understand and use. For example, the `git status` command is easy to understand and tells you exactly what you need to know: the current status of your git repository.

The output of git commands is also easy to read. The `git status` command, for example, outputs a list of modified files and whether they are staged for commit or not. This output is easy to scan and understand at a glance.

Finally, the git documentation is excellent. The `git` command itself has a built-in help system that is easy to follow. For example, the `git help` command displays a list of all available git commands, and the `git help <command>` command displays help documentation for a specific git command.

Examples of other CLI tools:

Git: github, gitlab
CSPs: azure, aws, heroku
K8s: minikube, kubectl
Sites creation: npm, vue, gatsby
Compilers: gcc, cl, clang

Distribute the tool as a single file with no dependencies

When you’re distributing a CLI tool, you want to make it as easy as possible for users to get up and running. The last thing you want is for users to have to install a bunch of dependencies just to use your tool.

One way to avoid this is to distribute your CLI tool as a single file. This way, users can simply download the file and run it without having to install anything else.

Another way to avoid dependencies is to use a language that doesn’t require any dependencies. For example, Go is a great language for building CLIs because it doesn’t require any dependencies. This means that users can simply download the Go binary and run your CLI tool without having to install anything else.

If you cannot get rid of dependencies, keep the dependency footprint small. This means that your CLI tool should only have a few dependencies, and those dependencies should be widely used and well-maintained.

You could also try bundling an application and all its dependencies into a single package. For instance, PyInstaller is a bundling tool for Python.

Make sure your commands are easy to understand

Your CLI tool should be easy to use, and that starts with your commands. Your commands should be short, descriptive, and easy to understand. For example, the npm install command is short and easy to understand. Ideally, you want your commands to be so simple that users don’t even need to read the documentation to understand them.

Make sure your output is easy to read

When you’re designing the output of your CLI tool, you want to make sure it’s easy to read. Users shouldn’t have to dig through a bunch of confusing output just to find the information they need.

To make your output easy to read, you should use clear and concise language. You should also use spacing and indentation to make your output more readable.

Provide good error messages

One of the most important aspects of a great CLI experience is providing good error messages. Your users should be able to understand what went wrong when they see an error message, and they should be able to easily find the documentation they need to fix the problem.

To write good error messages, you need to understand what went wrong and why it went wrong. Once you have that information, you can craft a message that will help your users understand the problem and how to fix it.

Make your commands discoverable

Another important aspect of a great CLI experience is making your commands discoverable. Your users should be able to find the commands they need without having to search through documentation.

The best way to make your commands discoverable is to use a consistent naming scheme. For example, all of the commands for managing users could start with “user-”. Or, all of the commands for managing files could start with “file-”.

Your users should also be able to type in “help” to see a list of all the commands available to them. And, each command should have its own help documentation that users can access by typing in “help ”.

Conclusion

Creating a great CLI experience is more about making your commands work well and follow best practices, rather than reinventing the concept of a CLI. The best way to learn about building great CLIs is to study other CLIs that have a great reputation and analyze what makes them great.