NAV Navbar

CLI Overview

###########################################################
# Windows specific command prompt instructions shown here #
###########################################################
#########################################################
# macOS specific command prompt instructions shown here #
#########################################################

The Bonsai Command Line Interface (CLI) is a text-based tool that enables you to configure and control the Bonsai Artificial Intelligence Engine. The CLI is especially useful for automation and connection to other tools. Currently, there are some actions that can only be performed using the CLI, such as loading your Inkling file and connecting your simulator.

This guide will walk you through how to install the Bonsai CLI, setup your first project, and get a simulator running, all from your local computer. If you haven’t yet, it will be helpful to read the Quick Start Overview to give context to the commands you’ll be running in this guide.

The reference document for all of the commands you will see in this guide can be found in the CLI Reference.

Install Prerequisites

Before you begin, you will need to have access to the Bonsai Platform preview. If you don’t have access yet, request access at bons.ai.

The next section walks you through how to install Git, Python, and pip, but if you’re already ahead of the curve and have them all installed, skip down to Setup the Bonsai CLI.

There are three sets of install instructions, please pick the one that suits your situation:

  1. If you have Anaconda installed on your system, skip down to Install with Anaconda.
  2. If you have Chocolatey (Windows) or Homebrew (macOS) installed on your system, skip down to Install with Chocolatey or Homebrew.
  3. If you do not have Chocolatey, Homebrew, or Anaconda installed on your system continue to follow our Manual Install intructions below.

Manual Install

Windows

  • pip: Python version 2.7.9 and greater come with pip, but if for some reason you need to use a different version of Python please follow these instructions.

Great! Now that you have Git, Python, and pip installed, you can skip down to Setup the Bonsai CLI.

macOS

  • Git: Git is more than likely already installed on your computer if you have Xcode, but if not, run git from your command prompt and the system will prompt you to install.
  • Python: Download and install Python (3.6 or 2.7) from python.org.
  • pip: Python version 2.7.9 and greater come with pip (or pip3 for version 3+), but if for some reason you need to use a different version of Python please follow these instructions.

Great! Now that you have Git, Python, and pip installed, you can skip down to Install the Bonsai CLI.

Install with Chocolatey or Homebrew

If you do not have Chocolatey or Homebrew installed on your system, please go to the Manual Install or Install with Anaconda instructions.

Python 2

choco install git
choco install python2
brew install python

Python 3

choco install git
choco install python
brew install python3

Windows

If you’re already familiar with Chocolatey, follow these instructions.

macOS

If you’re already familiar with Homebrew, follow these instructions.

  • Git: Git is more than likely already installed on your computer if you have Xcode, but if not, run git from your command prompt and the system will prompt you to install.
  • Python: Run the install command on the tab to the right to brew install the Python version of your choice.

Install with Anaconda

conda install git

If you do not have Anaconda installed on your system, please go to the Manual Install or Install with Chocolatey or Homebrew instructions.

conda is a tool for installing and managing Python and R dependencies. Anaconda includes Python and pip, so all you need to do is install Git if you haven’t already. For more information, refer to the Anaconda website.

Install the Bonsai CLI

Python 2 and Anaconda

pip install bonsai-cli
bonsai configure # for authentication

Python 3

# same as above
pip3 install bonsai-cli
bonsai configure # for authentication

From your command prompt, install the Bonsai Command Line Interface tool and configure (authenticate) it. bonsai configure will ask for your Access Key. You can find your Access Key in your Bonsai Account Settings.

Setup Your Project

Clone a Sample Project

git clone https://github.com/BonsaiAI/gym-mountaincar-sample

Clone a sample simulation project with git clone. For this guide we’ll be walking you through OpenAI Gym’s Mountain Car environment, one of the supported Bonsai simulators.

If you wish to experiment with your own project at this stage you can. Your project will need an Inkling (.ink) file and a simulator file. Many other projects can be found on the BonsaiAI GitHub page.

Install Project Requirements

Python 2 and Anaconda

cd gym-mountaincar-sample
pip install -r requirements.txt

Python 3

# same as above
cd gym-mountaincar-sample
pip3 install -r requirements.txt

Enter into the Mountain Car folder and then install the Mountain Car requirements from OpenAI Gym with pip.

Create Your BRAIN

bonsai create myMountainCarBrain

Create your BRAIN (and its related project file) with bonsai create and give it a name. We used myMountainCarBrain in the example code but you can name it whatever you’d like. You will view your BRAIN’s training progress on the BRAIN’s Details page which can be found on the BRAIN dashboard.

bonsai push

Uae bonsai push to upload the cloned Mountain Car project and its associated files to the Bonsai AI Engine for training.

Train Your BRAIN

Almost there! Time to tell the Bonsai AI Engine to prepare a new BRAIN version for training. There are currently two options for training a BRAIN, one is to run a simulator remotely using Bonsai’s servers, and the other is to run a simulator locally with your own computer.

Simulators which can be trained remotely include EnergyPlus, OpenAI Gym’s, and simple simulators all found on our Examples documentation. If the simulator is not one that we support remotely, you’ll need to run it locally.

Train Remotely

bonsai train start --remote

Start training your BRAIN with bonsai train start --remote.

Remote training is the best way to train BRAINs that need to ran overnight or for multiple days at a time. There is no disconnection of the simulator to the server like there can be when training locally.

Train Locally

bonsai train start

Python 2

python mountaincar_simulator.py --train-brain=myMountainCarBrain --headless

Python 3

# same as above
python3 mountaincar_simulator.py --train-brain=myMountainCarBrain --headless

Start training your BRAIN with bonsai train start.

Once you have started training mode it’s time to start running your simulator locally by calling Python and then the simulator file. Training will begin automatically and if the simulator gets disconnected, training resumes from the same point when the simulator is reconnected if it’s within an hour of the disconnect. If you want your training to take place overnight, make sure that your computer won’t go to sleep and disconnect for more than an hour or that training time will be lost!

View your BRAIN training status

View your BRAIN’s training status as it trains on the simulator by going to the BRAIN’s Dashboard page on beta.bons.ai. Training Mountain Car takes about an hour to get sufficient training to beat the game most of the time. If you want flawless victories each time the simulator can take up to 2 hours before you’ll see the graph level out.

Fully Trained BRAIN

There is no automatic ending to training, you can train forever, but there will be diminishing returns after a couple of hours. You can play around with training for 15 mins, 30 mins, 1 hour, etc and use your BRAIN to see how well it plays each time! It takes about 700 episodes to train the BRAIN correctly. Our ideal target is an average reward of -195 or higher over 100 consecutive episodes.

Stop Training

bonsai train stop

Once we’ve gotten to this level of performance (or sooner if you prefer), CTRL-C to disconnect the simulator (if you are running it locally), then bonsai train stop will end the training, and proceed to prediction.

Predict with Your BRAIN

Python 2

python mountaincar_simulator.py --predict-brain=myMountainCarBrain --predict-version=latest

Python 3

# same as above
python3 mountaincar_simulator.py --predict-brain=myMountainCarBrain --predict-version=latest

After your BRAIN is finished training it can play the Mountain Car game. How well it does depends on how long you let it train! Using your BRAIN involves calling Python on your simulator file, but now in prediction mode with --predict-version=latest which will use the version of the latest training session that you just ran.