The MSBot CLI for the Microsoft Bot Framework

by Michael Szul on Sat Jun 16 2018 06:00:00

Since the SDK v4 announcements at Microsoft Build, there have been a lot of new Bot Framework items and functionality to investigate and work with. The Bot Emulator v4, for example, is a huge upgrade to the previous Bot Emulator, and shows that Microsoft is dedicated to creating better tooling for end-to-end chatbot development.

I've been busy outlining several YouTube tutorial collections, and trying to find time to record a handful of videos for my YouTube channel. The first new tutorial series I decided to record deals with the Bot Emulator v4, but the last video in that series actually goes over the MSBot command line utility--one of several tools that Microsoft is developing for command line tooling.

I recently updated the README at Microsoft's botbuilder-tools GitHub repository to reflect some of the changes in the MSBot tool, as well as the appropriate parameters and parameter switches. This way the README reflects the appropriate configurations available for the services in the Bot file.

All of the configuration you can do with the Bot Emulator (including attaching services) is really just a GUI interface to update the *.bot file, and all of this can also be accomplished on the command-line via the new MSBot CLI.

You can install the MSBot utility using the Node package manager:

npm install -g msbot

Creating a Bot File

To create a Bot file, use the command line to initialize a bot project.

msbot init

You will then be walked through a series of steps to name your bot, and add an endpoint. Doing so will create a *.bot file with the localhost endpoint as a service in the array.

{
        "name": "test",
        "description": "",
        "secretKey": "",
        "services": [
            {
                "type": "endpoint",
                "name": "test",
                "id": "http://localhost:3978/api/messages",
                "appId": "",
                "appPassword": "",
                "endpoint": "http://localhost:3978/api/messages"
            }
        ]
    }

You can also pass some command line parameters to the MSBot utility to jumpstart the process.

msbot init -n "test" -e "http://localhost:3978/api/messages"

Alternatively:

msbot init --name "test" --endpoint "http://localhost:3978/api/messages"

Adding Services

Once you have a Bot file, you can add services from the command line using msbot connect. You can add additional endpoints, an Azure Bot Service, LUIS, QnA Maker, and Dispatch--all the same items that you can add from the Bot Emulator services pane.

Each service will have different required command line parameters so be mindful. You can always use the -h or --help switch to see the available parameters for each service. For example, to bring up the Azure Bot Service help, you can type msbot connect azure -h.

Endpoint

When you first create a Bot file, it has a localhost endpoint service for local development, but you can add additional endpoints, if needed. In fact, if you connect an Azure Bot Service, it adds two service entries: One for the Azure Bot Service and another for the endpoint of that service.

To add an endpoint:

msbot connect endpoint -e "https://my-fake.azurewebsites.net/api/messages -a MY_APP_ID -p MY_APP_PASSWORD

For the remainder of this post, I will use the short command line switch rather than the full one (where able). You can find all variations--and all command line switches--in the botbuilder-tools GitHub repository mentioned earlier.

Note that you can also add a name for your endpoint with the -n command line switch.

{
        "type": "endpoint",
        "name": "szul-test",
        "id": "https://my-fake.azurewebsites.net/api/messages",
        "appId": "032387dd-c6e8-467d-a81f-d09eb2c1660e",
        "appPassword": "thisispassword",
        "endpoint": "https://my-fake.azurewebsites.net/api/messages"
    }

Azure Bot Service

You will want to add an Azure Bot Service for production (or staging) deployment in Azure.

msbot connect azure -i testbot -n "Test Bot" -a "562789d2-a344-445c-b4b1-41e8583f9f72" -p 1abHDN3421342 -e https://testbot.azurewebsites.net/api/messages -t "be7b8d72-10ae-4ac1-8527-340bf93e459a" -s "60436c45-7f80-46e8-ba10-a8c2f6e4a737" -r "Test"

As mentioned above, this will create two entries in the services array in the Bot file.

"services": [
        {
            "type": "endpoint",
            "name": "szul-test",
            "id": "https://my-fake.azurewebsites.net/api/messages",
            "appId": "032387dd-c6e8-467d-a81f-d09eb2c1660e",
            "appPassword": "thisispassword",
            "endpoint": "https://my-fake.azurewebsites.net/api/messages"
        },
        {
            "type": "abs",
            "id": "testbot",
            "name": "Test Bot",
            "tenantId": "562789d2-a344-445c-b4b1-41e8583f9f72",
            "subscriptionId": "562789d2-a344-445c-b4b1-41e8583f9f72",
            "resourceGroup": "TEST"
        }
    ]

LUIS

Let's face it; You're likely to always use LUIS. It goes hand-in-hand with building an effective chatbot. You can connect LUIS to your chatbot as well.

msbot connect luis -n "train-status" -a "032387dd-c6e8-467d-a81f-d09eb2c1660e" -v 1 --authoringKey "032387dd-c6e8-467d-a81f-d09eb2c1660e" --subscriptionKey "032387dd-c6e8-467d-a81f-d09eb2c1660e"

You will need to supply the name, version, application ID, and authoring key. The subscription key is optional.

{
        "type": "luis",
        "id": "032387dd-c6e8-467d-a81f-d09eb2c1660e",
        "name": "train-status",
        "version": "1",
        "appId": "032387dd-c6e8-467d-a81f-d09eb2c1660e",
        "authoringKey": "032387dd-c6e8-467d-a81f-d09eb2c1660e",
        "subscriptionKey": "032387dd-c6e8-467d-a81f-d09eb2c1660e"
    }

QnA Maker

If you want to have a knowledge base in your chatbot, you are likely going to want to use QnA Maker, which is Microsoft's no-code solution to creating FAQ bots.

msbot connect qna -n "test-kb" -k "032387dd-c6e8-467d-a81f-d09eb2c1660e" --subscriptionKey "032387dd-c6e8-467d-a81f-d09eb2c1660e" --endpointKey "032387dd-c6e8-467d-a81f-d09eb2c1660e" --hostname "https://myqna.azurewebsites.net"

For the QnA Maker, you will want to supply the name, knowledge base ID, subscription key, endpoint key, and hostname.

{
        "type": "qna",
        "id": "032387dd-c6e8-467d-a81f-d09eb2c1660e",
        "name": "test-kb",
        "kbId": "032387dd-c6e8-467d-a81f-d09eb2c1660e",
        "subscriptionKey": "032387dd-c6e8-467d-a81f-d09eb2c1660e",
        "endpointKey": "032387dd-c6e8-467d-a81f-d09eb2c1660e",
        "hostname": "https://myqna.azurewebsites.net"
    }

Dispatch

As a part of managing services, Microsoft is attempting to allow developers to better work with multiple cognitive service models. This is where the dispatch service comes into play.

As of this writing, the dispatch service is still in development, and is not officially available.

msbot connect dispatch -n "test" -a "032387dd-c6e8-467d-a81f-d09eb2c1660e" -v 1 --authoringKey "032387dd-c6e8-467d-a81f-d09eb2c1660e" --subscriptionKey "032387dd-c6e8-467d-a81f-d09eb2c1660e"

Other Options

All connect services allow you to supply a secret (--secret), if you are encrypting your services. In addition, if your *.bot file is not in your working directory, you can supply the path to your Bot file to the CLI using -b or --bot. Two other options are the --stdin switch for accepting the JSON as standard input, and the --input switch for accepting a file that contains JSON.

If you want to list connected services without opening the Bot file in an emulator, you can use msbot list. To disconnect a service, the easiest way is to pass in the name of the service: msbot disconnect test-kb.

The MSBot CLI has taken chatbot management and allowed it to be moved to the command line, giving it a roadmap to grow into a highly effective scripting utility for chatbot management, deployment, and configuration. It'll be interesting to see how this utility evolves as we get closer to the official SDK v4 release.

▲hckr.fyi // thoughts