3. Command-line interface

3.1. Summary

The command-line interface (CLI) is self-documenting. To begin, try:

rerobots help

which will result in a message similar to the following

usage: rerobots [-h] [-V] [-t FILE]
                {info,isready,addon-cam,addon-mistyproxy,addon-drive,list,search,wdinfo,launch,terminate,version,help}
                ...

rerobots API command-line client

positional arguments:
  {info,isready,addon-cam,addon-mistyproxy,addon-drive,list,search,wdinfo,launch,terminate,version,help}
    info                print summary about instance.
    isready             indicate whether instance is ready with exit code.
    addon-cam           get image via add-on `cam`
    addon-mistyproxy    get proxy URL via add-on `mistyproxy`
    addon-drive         send motion commands via add-on `drive`
    list                list all instances owned by this user.
    search              search for matching deployments. empty query implies
                        show all existing workspace deployments.
    wdinfo              print summary about workspace deployment.
    launch              launch instance from specified workspace deployment or
                        type. if none is specified, then randomly select from
                        those available.
    terminate           terminate instance.
    version             print version number and exit.
    help                print this help message and exit

optional arguments:
  -h, --help            print this help message and exit
  -V, --version         print version number and exit.
  -t FILE, --jwt FILE   plaintext file containing API token; with this flag,
                        the REROBOTS_API_TOKEN environment variable is
                        ignored.

Call help to learn more about commands, e.g., rerobots help info to learn usage of rerobots info.

To use an API token, assign it to the environment variable REROBOTS_API_TOKEN, or give it through a file named in the command-line switch -t.

3.2. Example

The following video demonstrates how to search for types of workspaces, request an instance, and finally terminate it. The same example is also presented below in text.

Before beginning, get an API token (from the Web UI). In this example, we assume that it is saved to a file named jwt.txt.

Search for workspace deployments:

$ rerobots search misty
2c0873b5-1da1-46e6-9658-c40379774edf    fixed_misty2

Get more information about one of them:

$ rerobots wdinfo 2c0873b5-1da1-46e6-9658-c40379774edf
{
  "id": "2c0873b5-1da1-46e6-9658-c40379774edf",
  "type": "fixed_misty2",
  "type_version": 1,
  "supported_addons": [
    "cam",
    "mistyproxy"
  ],
  "desc": "",
  "region": "us:cali",
  "icounter": 641,
  "created": "2019-11-18 22:23:57.433893",
  "queuelen": 0
}

Notice that queuelen = 0, i.e., this workspace deployment is available, and requests to instantiate from it now are likely to succeed. To do so,

$ rerobots launch 2c0873b5-1da1-46e6-9658-c40379774edf
f7856ad4-a9d7-43f5-8420-7073d10bceec

which will result in a secret key being written locally to the file key.pem. This key should be used for ssh connections, e.g., with commands of the form ssh -i key.pem. Get information about the new instance:

$ rerobots info f7856ad4-a9d7-43f5-8420-7073d10bceec
{
  "id": "f7856ad4-a9d7-43f5-8420-7073d10bceec",
  "deployment": "2c0873b5-1da1-46e6-9658-c40379774edf",
  "type": "fixed_misty2",
  "region": "us:cali",
  "starttime": "2020-05-23 02:05:20.311535",
  "rootuser": "scott",
  "fwd": {
    "ipv4": "147.75.70.51",
    "port": 2210
  },
  "hostkeys": [
    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBPd5tTJLAksiu3uTbGwkBKXFb00XyTPeef6tn/0AMFiRpomU5bArpJnT3SZKhN3kkdT3HvTQiN5/dexOCFWNGUE= root@newc59"
  ],
  "status": "READY"
}

Finally, terminate the instance:

$ rerobots terminate f7856ad4-a9d7-43f5-8420-7073d10bceec