microsoft/botframework-cli

README

PRE-ARCHIVE NOTICE:

This project is no longer actively maintained and will be archived in January of 2025. Functions of this project were superseded by Microsoft Copilot Studio,

Archived projects are still available for use by developers, however they will not be actively maintained or serviced by Microsoft.

BF Command Line Interface

BF Command Line Interface (CLI) tool replaces and aggregates the collection of standalone tools used to manage Bot Framework bots and related services into one cohesive and consistent interface.

The old tools have been deprecated. All new investments, bug fixes, and new features will be implemented in the new consolidated BF CLI alone.

Installation

BF is based on the Node.js platform and the OClif framework where it inherits its command line parsing style, and plugin architecture platform.

You must download the following prerequisites:

Node.js version 14

Install the tool using the following command:

$ npm i -g @microsoft/botframework-cli
$ bf

Troubleshooting

For installation failures in some Linux platforms, try one of the following workarounds:

Upgrade npm to version 7.9
Install without the '-g' option and use npx

$ npm i @microsoft/botframework-cli
$ npx bf

Available Commands

The following commands are currently available:

See Porting Map for a mapping reference between old and new tools

Overview

The Bot Framework Command Line Interface (BF CLI) cross-platform tool is used to manage Bot Framework bots and related services. It is part of the Microsoft Bot Framework, a comprehensive framework for building enterprise-grade conversational AI experiences. In particular, BF CLI provides fundamental functionality when used in conjunction with Continuous Integration, and Continuous Deployment (CI/CD) pipelines.

As you build your bot, you may also need to integrate AI services like LUIS.ai for language understanding, QnAMaker.ai for your bot to respond to simple questions in a Q&A format, and more. The bf luis command is used to convert, and translate language definition .lu files or generate corresponding source (C# or JavaScript) code as well as deploy the local files, train, test, and publish them as Language Understanding models within the LUIS service. If used to define QnAMaker question/answer Knowledgebase, use the bf qnamaker command to create and manage QnAMaker assets both locally, and on the QnAMaker service. Please refer to the lu library documentation for extended discussion on how to work with .lu file formats. Note: You may be familiar with the Luis command if you used the legacy LuDown and LuisGen tools.

As your bot grows in sophistication, use bf orchestrator command to generate a dispatcher LU from the language assets in your solution similar to the legacy dispatch CLI. Then, you may use the Orchestrator recognizer for dispatching across subsequent services and skills. Use bf orchestrator command to evaluate language model quality. Use Orchestrator to to route intents across multiple bot modules such as LUIS models, QnA knowledgebases, and assist in routing messages to backend bot skills.

To test and refine your bot, you can use the new V4 Bot Framework Emulator. The Bot Framework Emulator is a cross-platform Electron application that enables you to test and debug your bots on local machine or in the cloud.

Also, during early designs stages you may want to create mockup of conversations between the user and the bot for the specific scenarios your bot will support. Use bf chatdown command to author conversation mockup .chat files and convert them into rich transcripts and view the conversations in the the Emulator.

With the Azure CLI Bot extension (az bot command), you can create, download, publish, configure channels with the Azure Bot Service. It is a plugin that extends the functionality of Azure CLI to manage your Azure Bot Service assets.

Lastly, although the CLI is primarily used in code-first solutions and CI/CD pipeline automation, since the underlying libraries are also used in Bot Framework Composer, it can be used to provision and organize some assets for Bot Framework Composer (such as .dialog generation, Orchestrator evaluation, exporting LUIS & QnAMaker models).

Issues and Feature Requests

Please file issues and feature requests here.

Also, see current known issues.

Thank you for your support.

Privacy

Privacy is very important to us. BF CLI contains optional instrumentation that is designed to help us improve the tool based on anonymous usage patterns. It is disabled, opted-out by default. If you elect to opt-in, we will gather some usage data as follows:

Command group calls
Flags used excluding specific values (i.e. if used parameter --folder:name, we will only gather the use of --folder but will not capture name).

To disable data collection see the bf config command.

Please refer to Microsoft Privacy Statement for more details.

Enable Telemetry in Continuous Integration Pipelines

Per above, Microsoft will only collect anonymous data to help improve the CLI. To set your CI/CD pipeline telemetry collection behavior set the following OS environment variable:

set BF_CLI_TELEMETRY = true : Bypass prompts and enables telemetry collection.
set BF_CLI_TELEMETRY = false : Bypass prompts and disables telemetry collection (default).
BF_CLI_TELEMETRY = null (absent) : If no value is set in configuration file defaults to false - disabled.

Nightly builds

Nightly builds are generated using the latest code. Therefore, they may not be stable, and most likely lack up to date documentation. These builds are better suited for more experienced users, although everyone is welcome to use them and provide feedback.

Install using npm:

npm i -g @microsoft/botframework-cli@next

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Reporting Security Issues

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at secure@microsoft.com. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.