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                           Enable verbose debugging output.
  --version                         Show the version and check if Bonsai is up
                                    to date.
  --sysinfo                         Show system information.
  --timeout INTEGER                 Set timeout for CLI API requests.
  --enable-color / --disable-color  Enable/disable color printing.
  -h, --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.
  help       Show this message and exit.
  list       Lists BRAINs owned by current user.
  pull       Downloads project file(s) from a BRAIN.
  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.

How to use timeout

bonsai --timeout [INTEGER] [COMMAND]

Example: bonsai --timeout 10 list

Note: Order matters because it is a top level command. The following would not work: bonsai list --timeout 10

bonsai configure

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

  Authenticate with the BRAIN Server.

Options:
  --username TEXT    Provide username.
  --access_key TEXT  Provide an access key.
  --show      Prints active profile information.
  -h, --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 your access to write Inkling code to a specific BRAIN.

You can find your access key at https://beta.bons.ai/accounts/settings/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
                       (e.g. "demos/cartpole").
  --json               Output json.              
  -h, --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 download [OPTIONS] BRAIN_NAME

  Downloads all the files related to a BRAIN.

Options:
  -h, --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.

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

bonsai list shows you the BRAINs on your account. You must have your Bonsai account configured with bonsai configure before you can see this list.

bonsai pull

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

  Downloads project file(s) from a BRAIN.

Options:
  --all         Option to pull all files from targeted BRAIN.
  --brain TEXT  Override to target another BRAIN.
  -h, --help    Show this message and exit.

bonsai pull asks you one by one whether you would like to download the specified file. You can respond with [Y/n] to the prompt for each file in the BRAIN’s project. If you would like to automatically download all files from the BRAIN then bonsai pull -all will update all files without asking you which ones to download.

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
  --json          Output json.
  -h, --help      Show this message and exit.

bonsai push uploads the project file contents specified in the .bproj file 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.

You can not push files exceeding 640KB to the server.

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.
  --json          Output json.
  -h, --help      Show this message and exit.

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

bonsai switch

$ bonsai switch --help
Usage: bonsai switch [OPTIONS] PROFILE

  Change the active configuration section.

  For new profiles you must provide a url with the --url option.

Options:
  --url TEXT  Set the brain api url.
  --show      Prints active profile information.
  -h, --help  Show this message and exit.

Available Profiles:

bonsai switch changes your current profile to a different configuration as specified in your .bonsai file. If you wish to create a new profile you can do so with the --url option which creates a configuration you can use again in the future. bonsai switch or bonsai switch -h/--help will print available profiles.

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:
  -h, --help  Show this message and exit.

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

bonsai train has no functionality 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.
  --json          Output json.
  -h, --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 disconnects, the BRAIN remains in training mode, and it will train again where it left off when the simulator reconnects (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 resume

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

  Resume training on the specified BRAIN.

Options:
  --brain TEXT    Override to target another BRAIN
  --project TEXT  Override to target another project directory.
  --remote        Resume simulator remotely on Bonsai's servers.
  --json          Output json.
  -h, --help      Show this message and exit.

bonsai train resume resumes training on an existing trained version of a BRAIN. You can stop and resume a BRAIN as needed.

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.
  -h, --help      Show this message and exit.

bonsai train status gets the current training status of your BRAIN.

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.
  --json          Output json.
  -h, --help      Show this message and exit.

bonsai train stop stops (or pauses) training on the current BRAIN. You can resume training with bonsai train resume.

Projects and Config Files

The Bonsai command-line interface works with three files. A .bonsai file in your user directory, a .bproj 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

Your user directory contains the .bonsai file. This file 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.ai"
    }
}

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 included in this BRAIN. Directories may also be in the files list. Specifying a directory will include every file within that directory in the BRAIN. Only one inkling file per BRAIN is currently 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.ai"
    }
}

For users familiar with the Unix command line, file path expansion in the CLI will behave 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 multiple 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.