A day of work as an engineer in the tech industry typically involves performing hundreds of relatively complex tasks that could include anything from querying a database to debugging issues. The majority of these tasks require little thought from the engineer and are done quickly. However, there are also many actions that have non trivial set up and can be a real pain to do, especially if the task changes slightly between executions. Examples could be generating HMAC hashes for HTTP requests or decoding data from a database between some date range. Most engineers when faced with this situation will write a series of scripts to handle the setup for them. However, as time is generally not set aside in sprints to do this, these scripts are generally quite ad hoc in nature, probably completed in a rush and continuously hacked apart to deal with the various edge cases that crop up.
When you consider that this is being done by every engineer in your team/company as well, the time spent on this activity quickly mounts up.
This is where a good CLI can be worth its weight in gold. Firstly, by formalising and creating a code repository, you’ll give each engineer in your company a chance to contribute their solutions, allowing for the best approaches and ideas to become implemented and in turn used by the entire team. Furthermore, a time saving produced by one engineer can quickly become a time saving for all, increasing the overall efficiency of your team!
An added bonus of creating a CLI is that you can give it to potential clients or existing customers, especially if you’ve designed it to interact with an API you’ve produced. This will lower the barrier of entry to your platform and allow your clients to integrate with you much faster. Furthermore, if they have an issue, you can quickly replicate it as they’ll be using the exact same tools as your team, rather than a script they’ve cooked up, reducing the likelihood that the issue originated from poor implementation or lack of understanding.
If you’re thinking about building a CLI, I’ve put together a few recommendations below.
Some good practices for writing a CLI
- When implementing CLI functionality, it’s very important to keep each command as customisable and descriptive as possible. Engineers in general just won’t use a tool that isn’t straightforward or flexible enough.
- Make sure the CLI does all of the heavy lifting for the user.
- Consider breaking down particularly complex tasks into multiple commands.
- Spend some time making it simple to install like you would any other software package.
- Provide clear use case examples and documentation.
This is the CLI I’ve been building alongside my companies platform. The commands are quite descriptive, easy to interpret and the CLI itself deals with producing the request payloads and HMAC hashes for the user. By spending the time to do this straight away, it’s helped me rapidly develop new features and debug issues when they crop up.
After writing a few CLIs recently I recommend these libraries/frameworks:
If Python is your thing or you just want to write a CLI quickly then Docopt is a very solid option. You define your commands and documentation at the same time! Once you’ve written the usage instructions, Docopt will parse it and do all the argument parsing for you. All you need to worry about is writing the code to execute your commands. Docopt is simple to use but quite a powerful framework, giving you the ability to get something of off the ground quickly. Furthermore, as its in Python you can make it installable by pip quite easily, allowing it to be adopted by your team much faster.
Cobra and Viper
Cobra and Viper are frameworks in Go that provide a lot of extremely useful features out of the box such as config and environment variable parsing and merging. It might require a bit of work to integrate into existing applications but provides so much value that it’s almost always worth the effort! The framework is also quite useful to use when building any Go applications/services so investing some time into learning it is pretty worth while. Additionally it automatically generates the help output for you after some pretty simple command and flag definitions, creating a CLI that looks and feels very professional with minimal effort!