Ritchie CLI: An open-source automation tool for the rescue

Robots and engines representing automation

Ritchie CLI is a powerful tool for automation that’s quite easy to install, customizing, and what’s more fascinating from my perspective, sharing such customizations with other people into git based repositories, without having to clone them directly.

Its usage is based on executing pre-built commands from the terminal, for instance, this very simple case of starting MongoDB via Docker in our local:

Docker command to start MongoDB

Instead, we could create a script using Ritchie to perform the same operation by executing rit mongodb start as an alternative to creating a docker-compose file, or even better, the script could use the docker-compose along with other commands and scripts, the limit is our imagination.

The Basics


There’s no pre-requisite to start using it, and in the official site it’s well documented how to install it on different OS, initialize it and apply upgrades to keep it always up-to-date. It follows the link with instructions, pointing to the latest version while writing this post:


As mentioned previously, all the magic in using Ritchie resides in the possibility of sharing our scripts and executing those created by other people, and to achieve that, all we need to do is importing repositories.

List of providers to choose
Failing result since the repository doesn’t exist or doesn’t have a tag version created yet
Listing repositories already imported

By hitting rit init is asked if we wanna import the commons repository, which I recommend since it’s necessary for creating formulas of our own.


The idea with this post is presenting an overview of some possibilities we have using this flexible automation tool, so let’s dive deeper on the creation and usage of custom automation scripts, the formulas.

Language: Formulas can be implemented under multiple programming and scripting languages, so it’s up to you and your team to choose the one that better suit your needs in terms of execution and maintainability.

Creation: When we create a new formula from scratch a scaffold is generated with a hello world ready to be executed, so we can run it and use the existing code as a template for implementing our own logic.

Upon creation we’re asked to specify the formula workspace, and if left blank, the formula created is stored at a default location created on our behalf.

Moreover, after creating we can already hit the new formula and it’ll be built the first time followed by execution, and since the scaffold is based on user inputs, it prompts to the first expected parameter, like below:

Please verify that the formula was built via Docker in the image above, this is because Docker is Ritchie’s default runner, or has been chosen while hitting rit init. To choose “local” as default mode, execute rit set formula-runner, otherwise, invoke the formula appending “--local” to it.

Basic structure

The new formula will be comprised by some key files, necessary for Ritchie to know how to trigger our custom commands when the formula is executed. They are the following under “eureka” in the example below, except for the pom.xml, automatically generated when we choose Java for implementing the formula logic.

In general the files we have to worry about are the ones under src directory, given they store the formula scripts, and the config,json, for defining user inputs to be used in the source code as environment variables.

The docs/img is created once in each workspace, for us to optionally reference the banner in a git repository readme when we’re ready to push the code and create tag versions, so others can also be benefited using our formulas.

A world of possibilities

Github profile customization

Following the instructions from Guillaume Falourd on his Github profile, have imported his formulas repo in Ritchie and ran the script to generate a custom README.md, very similar to the one I’m currently using:

All I had to worry with was in creating a repository with the same name as my Github account, upload the file into it, push it, and was all set, way better than copying someone’s README file to edit with our data — templates save lives!

Deployment of legacy JAVA webapps with Docker

A scenario that came to mind was using Ritchie for automating the steps necessary to have some old webapps up and running quickly. In my case, there were two apps from college differing only by application server, but communicating with the same database.

It follows the activity diagram representing the formula created:

Creating the formula was just like mentioned above, just had to hit rit create formula and type the desired formula name, followed by the language, which was shell-bat in this case.

The second step was editing the formula.sh created, resulting in the following:

An equivalent formula.bat was also generated automatically to be executed on Windows machines, but I haven’t worried about it, since with tools like git bash it’s possible to execute Unix commands, or via powershell if available.

The environment variables used in the formula.sh have been specified in the config.json, as follows:

And there we go.. by creating the formula, editing the logic and pairing with input fields onto the config.json, as well as including into the src dir the docker-compose files for services started from the script, we’ve quickly built an automation abstracting the complexity of: 1) optionally starting a database, 2) pre-populating it with initial data if needed, 3) starting an application server, and 4) deploying legacy apps that need all that.

Ritchie formula in action
Services started using Docker via Ritchie

Observe this formula was implemented to run with “--local” arg due to starting services using Docker, although, it seems to be possible to run Docker inside Docker according to this issue, available from v2.12 🎉.

Here is the repository with the source code of the formula explored above, for importing as Ritchie repo and play around, hope you have fun! :)

Software engineer that besides tech stuff, loves music, chinchillas, coffee and pizza