Here at Stream, we recently build a powerful CLI to support our Feeds & Chat products. In doing so, we learned a lot about best practices when crafting a positive developer experience in the command line. Quick findings:
JavaScript is more powerful than you think. Tap into the massive ecosystem and a large number of open-source projects.
For inspiration, look at the functionality that Zeit and Heroku provide within their CLI to make for an awesome developer command line “experience”.
If your API/CLI requires data persistence, store that data in a cache directory that is specific to your CLI. Load this using a util file as we do at Stream. Also, note that the fs-extra package will come in handy for this type of thing (even though support is built into Oclif).
Oclif is the way to go, especially if you’re building a large CLI, as opposed to a single-command CLI. If you’re building a single-command CLI you can still use Oclif, just make sure to specify that it’s a single-command API when you’re scaffolding your CLI.
Don’t want to use a framework? That’s okay! The package minimist provides argument parsing in the command line and can easily be used within your project.
Use prompts, when you can, with enquirer or another package of your choosing. Users should be walked through the requirements of the command and asked for the data the command needs in order to execute properly. Note that this should never be required (e.g. let the user bypass the prompt if they pass the correct arguments).
Use colors when possible to make your CLI a little easier on the eye. Chalk serves as a great tool for this. If you have response data that is well enough structured, don’t just print it out to the user (unless that’s what they specify). Instead, drop it in a table using
Always allow the user to specify the output type (e.g. JSON), but default to a message that is human-readable.
Keep it fast! For time-consuming tasks such as file uploads or commands that require multiple API calls, we recommend showing a loading indicator to let the user know that work is being done in the background. If you’re looking for a package on npm, we recommend checking out ora.
The full blog post can be found here: https://medium.com/@nparsons08/crafting-a-command-line-experience-that-developers-love-68657b20c28d
