Getting started

Get the Workbench CLI tool set up on your local machine

Overview

Root enables flexible, modern digital insurance products to come to life in record time. We achieve this by abstracting & automating most of the complexity of insurance, exposing the rest in a flexible no-code/low-code environment.

The Workbench CLI tool is a command-line interface (CLI) tool. You can use this tool to set up, configure, and test insurance products on your local machine, and push changes to Root.

This tutorial is a step-by-step guide to setting up the Workbench CLI tool on your local machine. The tutorials that follow will guide you on how to use the Workbench CLI tool to make changes to an existing insurance product on Root.

Read more about the functionality offered by the Workbench CLI tool in the Workbench CLI tool commands guide. For an overview of the product features you can configure, and how to configure them, see the Product modules overview guide.

Step 1: Get set up on Root

To complete this tutorial, a Root team member needs to set you up on Root by creating a Root account and giving you access to the Root management dashboard. Ensure you have access before continuing. You can log in to the dashboard at https://app.root.co.za.

Create an organization and add a product module

Once you have access, you can create a playground organization by clicking on the "Create an organization" button. You can call this organization Playground - [your name]. Select the Dinosure Onboarding Template and add the following:
Name: Dinosure [your name]
Key: dinosure_[your_name]

🚧

Root access required

From this step forward you need access to Root. Get in touch with us if you're interested to play around or build a new insurance product. If you're already in touch but stuck, reach out to our team at [email protected] and we'll get you back on the road soon.

Step 2: Set up your local environment

To use the Workbench CLI tool effectively, you need a few things installed on your machine. This works on Mac, Windows & Linux.

a. Install NodeJS

We need to install NodeJS in order to set up and use the Workbench CLI tool.

Download NodeJS and install it to your machine.

b. Install VS Code

We need a code editor in order to use the Workbench CLI tool. We generally prefer VSCode, by Microsoft, but any IDE will work (like Atom, Sublime Text, etc).

Download VS Code and install it to your machine.

c. Install VS Code IntelliSense extension

To use the IntelliSense functionality on the Workbench CLI tool you will need to install the Project Snippets extension in VSCode.

Visit the Project Snippets to install the extension in VSCode.

Step 3: Install the Workbench CLI tool

Now that we have NodeJS and a code editor set up, we can proceed to install the Workbench CLI tool.

Mac instructions

If you are on Mac, open your Terminal.

In Terminal, type (or copy/paste) npm install -g @rootplatform/cli and press enter. This will download and install the Workbench CLI tool on your machine.

🚧

Directory permission issues

If run into permission errors when trying to install the tool, you can solve this by prefixing sudo to the command as follows: sudo npm install -g @rootplatform/cli. This will prompt for your system password (the one that unlocks your computer), and the password characters won't display as you type. Simply type your password and press enter. If you made a mistake, press enter to try again.

❗️

Node V16

If you're using Node V16, you might run into some usage issues. This can be resolved by using a tool like nvm to install and run Node V14.x or V12.x. If you use nvm, you may be able to configure your shell to automatically use the correct Node version when running commands in the product module directory.

Once that command finishes, the Workbench CLI tool and your environment is set up and ready to go.

Windows instructions

If you are on Windows, open Command Prompt.

In Command Prompt, type (or copy/paste) npm install -g @rootplatform/cli and press enter. This will download and install the Workbench CLI tool on your machine.

Once that command finishes, you can test that the Workbench CLI tool installed correctly by typing rp help. (All Workbench CLI tool commands use the format rp [options] [command].)

Your environment is now set up and ready to go.

Step 4: Create an API key

Let's generate an API key to use in the Workbench CLI tool. Open your playground organisation on the Root management dashboard by clicking on it. Navigate to Settings > API Keys. You'll find Settings at the bottom of the vertical blue menu on the left.

  1. Click "Create API Key".
  2. Give it a description like <your name> Workbench CLI tool, e.g. Sarah Workbench CLI tool.
  3. Click "Select all". Scroll down to Workbench and ensure read and write are selected.
  4. Click "Create API key", and keep this page open for the time being.

Note: You can only see the API key once, so if you've accidentally closed the window, delete the key and create a new one.

Step 5: Clone a product module to your local machine

When you created your organization on the dashboard, the Root platform automatically created a toy product module to help you get started. This product module is identified by its product module key (for example, dinosure_onboarding_template_q1dew4w7).

To get the key for your onboarding product module, open your playground organisation on the Root management dashboard, and then open the settings menu by clicking the hammer and screw driver icon on the bottom left of the screen. Then click on "Product modules", and you should see your product module listed with its key.

You now need to clone this product module from Root to your local machine, so that you can work with it. To do this, go back to your Terminal (or Command Prompt) and clone (download) your Dinosure product module using the Workbench CLI tool.

  1. cd to your working directory, e.g. Documents, or just keep it where you are (Mac help, Windows help).
  2. Clone the product module using the command rp clone <api-key> <product-module-key>, for example: rp clone sandbox_YmZhNjk0... dinosure_onboarding_template_q1dew4w7.
  3. Now navigate with your Terminal/Command Prompt into that project directory using cd <product-module-key> (e.g. cd dinosure_onboarding_template_q1dew4w7). Try ls (Mac) or dir (Windows) to list all the files in the directory.

This new project directory can now be opened with your code editor to see and edit all the files and components of your Dinosure product module.

Well done! You have successfully completed the basic Workbench CLI tool setup. In the next tutorial you will use the Workbench CLI tool to implement your first product update.


Did this page help you?