Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/microsoft/botframework-cli

CLI Tools for the Microsoft Bot Framework
https://github.com/microsoft/botframework-cli

Last synced: about 1 month ago
JSON representation

CLI Tools for the Microsoft Bot Framework

Awesome Lists containing this project

README 

        



![Bot Framework CLI](./media/BFCLI-header.png)



# BF Command Line Interface

[![Build Status](https://fuselabs.visualstudio.com/SDK_Public/_apis/build/status/microsoft.botframework-cli?branchName=main)](https://fuselabs.visualstudio.com/SDK_Public/_build/latest?definitionId=713&branchName=main)



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](https://github.com/oclif/oclif) framework where it inherits its command line parsing style, and plugin architecture platform.



You must download the following prerequisites:



* [Node.js](https://nodejs.org/) 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](https://www.npmjs.com/package/npx)



~~~

$ npm i @microsoft/botframework-cli

$ npx bf

~~~



## Available Commands



The following commands are currently available:

* [Chatdown][1]

* [Config][2]

* [Dialog][3]

* [Luis][4]

* [QnAMaker][5]

* [Orchestrator][6]



See [Porting Map](https://github.com/microsoft/botframework-cli/blob/main/PortingMap.md) 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](https://github.com/Microsoft/botframework), 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](http://luis.ai) for language understanding, [QnAMaker.ai](http://qnamaker.ai) for your bot to respond to simple questions in a Q&A format, and more. The _[bf luis](./packages/cli#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](./packages/cli#bf-qnamaker)_ command to create and manage QnAMaker assets both locally, and on the QnAMaker service. Please refer to the[ _lu_ library documentation](./packages/lu)  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](https://github.com/microsoft/botbuilder-tools/tree/master/packages/Ludown) and [LuisGen](https://github.com/microsoft/botbuilder-tools/tree/master/packages/LUISGen) tools._



As your bot grows in sophistication, use [bf orchestrator][6] command to generate a dispatcher LU from the language assets in your solution similar to the legacy [dispatch](https://github.com/Microsoft/botbuilder-tools/tree/master/packages/Dispatch) CLI. Then, you may use the [Orchestrator][7] 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](https://github.com/Microsoft/BotFramework-Emulator/releases). The Bot Framework Emulator is a cross-platform [Electron](https://electronjs.org/) 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](./packages/cli#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](./AzureCli.md) (_az bot_ command), you can create, download, publish, configure channels with the [Azure Bot Service](https://azure.microsoft.com/en-us/services/bot-service/). It is a plugin that extends the functionality of [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) 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][8], it can be used to provision and organize some assets for Bot Framework Composer (such as .dialog generation, Orchestrator evaluation, exporting LUIS & QnAMaker models).  



### See Also

* [Detailed Usage Information](https://github.com/microsoft/botframework-cli/tree/main/packages/cli)

* [Bot Framework Homepage](https://dev.botframework.com/)

* [Azure Bot Service](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-overview-introduction?view=azure-bot-service-4.0)

* [LUIS](https://docs.microsoft.com/en-us/azure/cognitive-services/luis/index)

* [QnAMaker](https://docs.microsoft.com/en-us/azure/cognitive-services/qnamaker/)

* [Orchestrator][7]

* [Bot Design Guidelines](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-design-principles)



## Issues and Feature Requests

Please file issues and feature requests [here](https://github.com/microsoft/botframework-cli/issues).



Also, see current [known issues](https://github.com/microsoft/botframework-cli/labels/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](https://privacy.microsoft.com/en-US/privacystatement) 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:

```shell

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](https://opensource.microsoft.com/codeofconduct/).

For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or

contact [[email protected]](mailto:[email protected]) 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 [[email protected]](mailto:[email protected]). 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](https://technet.microsoft.com/en-us/security/dn606155) key, can be found in the [Security TechCenter](https://technet.microsoft.com/en-us/security/default).



Copyright (c) Microsoft Corporation. All rights reserved.



[1]: ./packages/chatdown/README.md

[2]: ./packages/cli#bf-config

[3]: ./packages/dialog/README.md

[4]: ./packages/luis/README.md

[5]: ./packages/qnamaker/README.md

[6]: ./packages/orchestrator/README.md

[7]: https://aka.ms/bf-orchestrator

[8]: https://docs.microsoft.com/en-us/composer/introduction