NAV Navbar

CLI Overview

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.

For information about changes in each CLI release, please refer to the CLI CHANGELOG on GitHub.

Installation

Install

Python 2 and Anaconda

pip install bonsai-cli

Python 3

# same as above
pip3 install bonsai-cli

The Bonsai CLI uses pip, the PyPA recommended tool for installing Python packages. Note that macOS running Python 3 requires the use of pip3 instead of pip.

Update

Python 2 and Anaconda

pip install -U bonsai-cli

Python 3

# same as above
pip3 install -U bonsai-cli

To update the Bonsai CLI to the most recent version please run the pip command.

Commands

Help Text

bonsai --help
Usage: bonsai [OPTIONS] COMMAND [ARGS]...

  Command line interface for the Bonsai Artificial Intelligence Engine.

Options:
  --debug / --no-debug  Enable/disable verbose debugging output.
  --version             Show the version and exit.
  --help                Show this message and exit.

Commands:
  configure  Authenticate with the BRAIN Server.
  create     Create a BRAIN and set the default BRAIN.
  delete     Delete a BRAIN.
  download   Downloads all the files related to a BRAIN.
  list       Lists BRAINs owned by current user.
  log        Display logs from remote training.
  push       Uploads project file(s) to a BRAIN.
  sims       Retrieve information about simulators.
  switch     Change the active configuration section.
  train      Start and stop training on a BRAIN.

Use bonsai COMMAND --help to get information about a specific command. You can use bonsai --help to view a list of options for COMMAND.

bonsai configure

$ bonsai configure --help
Usage: bonsai configure [OPTIONS]

  Authenticate with the BRAIN Server.

Options:
  --key TEXT  Provide an access key.
  --help      Show this message and exit.

bonsai configure sets up authentication between you (as a user) and the server. This enables the server to verify that you are allowed to write Inkling code to a specific BRAIN.

You can find your access key at https://beta.bons.ai/accounts/key.

bonsai create

$ bonsai create --help
Usage: bonsai create [OPTIONS] BRAIN_NAME

  Creates a BRAIN and sets the default BRAIN for future commands.

Options:
  --project TEXT       Override to target another project directory.
  --project-type TEXT  Specify to download and use demo/starter project files
                       (i.e. "demos/cartpole")
  --help               Show this message and exit.

bonsai create generates a new brain and names it BRAIN_NAME. It also sets the assumed BRAIN name for later commands.

BRAIN names may include (case insensitive, but case aware):

  • letters
  • numbers
  • dashes

If you’d like to use one of our pre-populated projects, you may run bonsai create --project-type TEXT in an empty directory where TEXT is any of the following projects:

  • demos/cartpole
  • demos/mountain-car
  • templates/starter-project

bonsai delete

$ bonsai delete --help
Usage: bonsai delete [OPTIONS] BRAIN_NAME

  Deletes a BRAIN. A deleted BRAIN cannot be recovered. The name of a
  deleted BRAIN cannot be reused.

Options:
  -h, --help  Show this message and exit.

bonsai delete deletes a BRAIN and its associated data from the Bonsai platform. Once a BRAIN is deleted, its data cannot be recovered, and its name cannot be reused.

bonsai download

$ bonsai download --help
Usage: bonsai.py download [OPTIONS] BRAIN_NAME

  Downloads all the files related to a BRAIN.

Options:
  --help  Show this message and exit.

bonsai download creates local copies of your BRAIN project files. This will contain your Inkling code and may also contain simulator code. This command works like git clone - it copies files into a new directory, and will not try and overwrite files that already exist.

bonsai list

$ bonsai list --help
Usage: bonsai list [OPTIONS]

  Lists BRAINs owned by current user or by the user under a given URL.

Options:
  --help  Show this message and exit.

bonsai list shows you the BRAINs you currently own or by a user under a given URL. You must have your Bonsai account configured with bonsai configure before you can see this list.

bonsai log

$ bonsai log --help
Usage: bonsai log [OPTIONS]

  Displays last 1000 lines of the running simulator's output.

Options:
  --brain TEXT    Override to target another BRAIN.
  --project TEXT  Override to target another project directory.
  --follow        Continually follow simulator's output.
  --help          Show this message and exit.

Displays stderr and stdout from the currently running simulator. This will display the last 1000 lines of the running simulator’s output. You can override the BRAIN you want to log if multiple are running at the same time or the project.

This command is meant for simulators running remotely on Bonsai’s servers using bonsai train start --remote. Simulators running locally will generally output this information at the command prompt.

If bonsai log --follow is used, then display will update when new logs exist. Use Ctrl-c to stop this command.

bonsai push

$ bonsai push --help
Usage: bonsai push [OPTIONS]

  Uploads project file(s) to a BRAIN.

Options:
  --brain TEXT    Override to target another BRAIN.
  --project TEXT  Override to target another project directory.
  --help          Show this message and exit.

bonsai push will upload the entire project file contents and all accompanying files to the Bonsai AI Engine and can be viewed on beta.bons.ai. You can override the BRAIN you want to push to or the project directory you want to push.

bonsai train

$ bonsai train --help
Usage: bonsai train [OPTIONS] COMMAND [ARGS]...

  Start and stop training on a BRAIN, as well as get training status information.

Options:
  --help  Show this message and exit.

Commands:
  start   Trains the specified BRAIN.
  status  Gets training status on the specified BRAIN.
  stop    Stops training on the specified BRAIN.

bonsai train has no funtionality itself. It will output the help to guide you to start, status, or stop training.

bonsai train start

$ bonsai train start --help
Usage: bonsai train start [OPTIONS]

  Trains the specified BRAIN.

Options:
  --brain TEXT    Override to target another BRAIN.
  --project TEXT  Override to target another project directory.
  --remote        Run a simulator remotely on Bonsai’s servers.
  --help          Show this message and exit.

bonsai train start turns on/enables training mode for the current BRAIN. The BRAIN trains whenever a simulator is connected.

When training locally, if the simulator is disconnected, the BRAIN remains in training mode, and it will train again where it left off when the simulator is reconnected up to an hour after being disconnected.

If bonsai train start --remote is used, then the simulator will run remotely on Bonsai’s servers for supported simulators.

bonsai train stop

$ bonsai train stop --help
Usage: bonsai train stop [OPTIONS] BRAIN_NAME

  Stops training on the specified BRAIN.

Options:
  --brain TEXT    Override to target another BRAIN.
  --project TEXT  Override to target another project directory.
  --help          Show this message and exit.

bonsai train stop turns off training mode for the current BRAIN.

bonsai train status

$ bonsai train status --help
Usage: bonsai train status [OPTIONS]

  Gets training status on the specified BRAIN.

Options:
  --brain TEXT    Override to target another BRAIN.
  --json          Output status as json.
  --project TEXT  Override to target another project directory.
  --help          Show this message and exit.

bonsai train status is used to see the current training status of your BRAIN.

bonsai sims list

$ bonsai sims list --help
Usage: bonsai sims list [OPTIONS]

  List the simulators connected to the BRAIN server.

Options:
  --brain TEXT    Override to target another BRAIN.
  --project TEXT  Override to target another project directory.
  --help          Show this message and exit.

bonsai sims list shows you all of the simulators you have connected to the BRAIN server.

Projects and Config Files

The Bonsai command-line interface works with three files. A .bonsai file in your user directory, a project file in the directory containing the Inkling files and simulator configuration for a BRAIN, and a .brains file that links a project file to a BRAIN in the same directory as the project file.

.bonsai file

[DEFAULT]
port = 443
username = bonsaiuser
accesskey = 55555555-5555-5555-5555-555555555555
webport = 443
webhost = beta.bons.ai
host = api.bons.ai
usessl = True

The .bonsai file is located in your user directory. It stores your username and an access token for access to the Bonsai servers. The bonsai configure CLI command will update this file and create it if it does not exist.

.bproj file

{
    "files": [
        "mybrain.ink",
        "my_simulator.py"
    ],
    "training": {
        "command": "python my_simulator.py",
        "simulator": "bonsai.python"
    }
}

Project files are created in the same directory as your Inkling files when you download or create a BRAIN with the CLI. The project file has a name like bonsai_brain.bproj and contains a JSON object that ties together the Inkling files, simulator files, and simulator configuration needed to train a BRAIN.

Files

files is a list of files to be included in this BRAIN. Directories may also be in the files list. When a directory is specified, every file within that directory is included in the BRAIN. Currently, only one inkling file per BRAIN is supported. If files specifies multiple Inkling files, only the first will be used and the remainder will be ignored.

There must be at least one valid path in the files list.

Globbing

Examples of globbing

{
    "files": [
        "*.ink",    # All inkling files in the current directory
        "*/*.py"    # All python source files from every subdirectory one level below cwd
    ],
    "training": {
        "command": "python my_simulator.py",
        "simulator": "bonsai.python"
    }
}

For users familiar with the Unix command line, file path expansion in the CLI will behave mostly as expected. There is no ~ expansion (in a Unix shell, this expands to the home directory), but *, ?, and character ranges expressed with [ ] will be correctly matched. Wikipedia has detailed information on globbing syntax.

You can test these on a generic shell under OSX and try the pattern from your project directory using the ls command, whose globbing support should mirror the Bonsai CLI’s in most cases.

Training

training is an object. The simulator field of that object points to a pre-configured simulation container inside the platform. The command field describes the command to run to start the simulator.

Current list of supported simulators for Docker cloud-hosted training:

.brains file

{
    "brains": [{
        "default": true,
        "name": "mybrain"
    }]
}

The .brains file links a project to a BRAIN on the server. You can link one project to many BRAINs. The file is located in the same directory as a project file.

  • name is a name of one of this user’s BRAINs.

  • default marks a named BRAIN as the default BRAIN to use with command operations.