readme.md

LUIS

The LUIS APIs tool allows communication with the LUIS endpoints via command line. You can also use this as a node module via an import.

Any endpoint listed in the documentation for the LUIS Programmatic APIs v2.0 is available using the CLI.

Language Understanding (LUIS.ai) allows your application to understand what a person wants in their own words. LUIS uses machine learning to allow developers to build applications that can receive user input in natural language and extract meaning from it.

Installation

Make sure you have Node.js >=8.5 and npm installed on your machine, then use:

npm install -g luis-apis

Configuration

A configuration object is required to provide the endpoint base path, app ID, version ID and the authoring key to each outbound call. There are 3 ways to provide this information to the CLI:

1. As a .luisrc file in the cwd. The json format for the .luisrc file is:

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "authoringKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "versionId": "x.x.xx",
  "region": "xxxxxxx"
}

The CLI has a utility command that walks through the creation of this file: luis init, or it can be created manually.

2. As arguments to the CLI: luis <verb> <resource> --appId <string> --versionId <string> --authoringKey <string> --region <string>

3. As environment variables: LUIS_APP_ID, LUIS_VERSION_ID, LUIS_AUTHORING_KEY, LUIS_REGION

You need a LUIS account to get an authoring key. Refer to Keys in LUIS for more information. If you have already built a LUIS application and would like to work on it using the LUIS CLI, you can determine the appId, versionId by following instructions in this Readme. See Publishing regions for help with authoring regions.

The CLI will first look for these named configuration variables in the arguments list, then inside the .luisrc file, then fallback to the environment variables.

Securing Your Access Key

To better secure your access key, it's recommended to omit the key from the .luisrc file and instead pass it in with the --authoringKey argument or store it as the LUIS_AUTHORING_KEY environment variable. If security is not a concern for your particular case, all configuration items can be stored in the .luisrc for convenience.

Overriding Configurations

Since configuration items can be passed as arguments to the cli, using arguments to specify the configuration will override the .luisrc and any environment variables that may have been specified.

CLI Usage

Basic usage: luis <action> <resource> <args...>

Command	Description
CompositeEntityRole
luis add CompositeEntityRole	Create an composite entity role for an entity in the application.
luis delete CompositeEntityRole	Delete a CompositeEntityRole.
luis get CompositeEntityRole --cEntityId <string> --roleId <string>	Get a CompositeEntityRole information.
luis update CompositeEntityRole --in entityRoleUpdateObject.json --cEntityId <string> --roleId <string>	Update a CompositeEntityRole.
CustomPrebuiltEntityRole
luis delete CustomPrebuiltEntityRole --entityId <string> --roleId <string>	Delete an entity role.
luis get CustomPrebuiltEntityRole --entityId <string> --roleId <string>	Get one entity role for a given entity.
luis update CustomPrebuiltEntityRole --in entityRoleUpdateObject.json --entityId <string> --roleId <string>	Update an entity role for a given entity.
Application
luis add app --in applicationCreateObject.json	Create a new LUIS app.
luis delete application --appId <string>	Delete an application.
luis get application --appId <string>	Get the application info.
luis import application --in jSONApp.json --appName <string>	Import an application to LUIS. Application structure should be included in in the request body.
luis update application --in applicationUpdateObject.json --appId <string>	Update the name or description of the application.
Applications
luis list apps --skip <integer> --take <integer>	List all of the user applications.
Assistants
luis list assistants	Get the endpoint URLs for the pre-built Cortana applications.
ClosedList
luis add closedlist --in closedListModelCreateObject.json	Add a closed list model to the application.
luis delete closedlist --clEntityId <string>	Delete a closed list model from the application.
luis get closedlist --clEntityId <string>	Get information of a closed list model.
luis update closedlist --in closedListModelPatchObject.json --clEntityId <string>	Add a batch of sublists to an existing closed list.
luis update closedlist --in closedListModelUpdateObject.json --clEntityId <string>	Update the closed list model.
ClosedListEntityRole
luis add closedListEntityRole --in entityRoleCreateObject.json --entityId <string>	Create an entity role for an entity in the application.
luis delete closedListEntityRole --entityId <string> --roleId <string>	Delete an entity role.
luis get closedListEntityRole --entityId <string> --roleId <string>	Get all entity roles for a given entity.
luis update closedListEntityRole	Update an entity role for a given entity.
ClosedListEntityRoles
luis list closedListEntityRoles --entityId <string>	Get all entity roles for a given entity.
ClosedLists
luis list closedlists --skip <integer> --take <integer>	Get information about the closed list models.
CompositeEntities
luis list compositeEntities --skip <integer> --take <integer>	Get information about the composite entity models.
CompositeEntity
luis add compositeEntity	Add a composite entity extractor to the application.
luis delete compositeentity --cEntityId <string>	Delete a composite entity extractor from the application.
luis get compositeEntity --cEntityId <string>	Get information about the composite entity model.
luis update compositeEntity --in compositeModelUpdateObject.json --cEntityId <string>	Update the composite entity extractor.
CompositeEntityChild
luis add compositeEntityChild --in compositeChildModelCreateObject.json --cEntityId <string>	Create a single child in an existing composite entity model.
luis delete compositeEntityChild	Delete a composite entity extractor child from the application.
Cultures
luis list cultures	Get the supported application cultures.
CustomPrebuiltDomain
luis add customprebuiltdomain --in prebuiltDomainCreateObject.json	Add a prebuilt domain along with its models as a new application.
luis add customprebuiltdomain --in prebuiltDomainObject.json	Add a customizable prebuilt domain along with all of its models to this application.
luis delete customPrebuiltDomain --domainName <string>	Delete a prebuilt domain's models from the application.
luis get customprebuiltdomain --culture <string>	Get all the available custom prebuilt domains for a specific culture.
CustomPrebuiltDomains
luis list customprebuiltdomains	Get all the available custom prebuilt domains for all cultures.
CustomPrebuiltEntities
luis get customPrebuiltEntities	Get all custom prebuilt entities information of this application.
CustomPrebuiltEntity
luis add customPrebuiltEntity --in prebuiltDomainModelCreateObject.json	Add a custom prebuilt entity model to the application.
CustomPrebuiltEntityRole
luis add CustomPrebuiltEntityRole --in entityRoleCreateObject.json --entityId <string>	Add a new CustomPrebuiltEntityRole.
CustomPrebuiltEntityRoles
luis list CustomPrebuiltEntityRoles --entityId <string>	Get all entity roles for a given entity.
CustomPrebuiltIntent
luis add customprebuiltintent --in prebuiltDomainModelCreateObject.json	Add a custom prebuilt intent model to the application.
CustomPrebuiltIntents
luis list customPrebuiltIntents	Get custom prebuilt intents information of this application.
CustomPrebuiltModels
luis list customPrebuiltModels	Get all custom prebuilt models information of this application.
Domains
luis list domains	Get the available application domains.
Endpoints
luis list endpoints --appId <string>	Return the available endpoint deployment regions and URLs.
Entities
luis list entities --skip <integer> --take <integer>	Get information about the entity models.
luis suggest entities --entityId <string> --take <integer>	Get suggestion examples that would improve the accuracy of the entity model.
Entity
luis add entity --in modelCreateObject.json	Add an entity extractor to the application.
luis delete entity --entityId <string>	Delete an entity extractor from the application.
luis get entity --entityId <string>	Get information about the entity model.
luis update entity --in modelUpdateObject.json --entityId <string>	Update the name of an entity extractor.
EntityRole
luis add entityRole --in entityRoleCreateObject.json --entityId <string>	Create an entity role for an entity in the application.
luis delete entityRole	Delete an entity role.
luis get EntityRole	Get all entity roles for a given entity.
luis update entityRole --in entityRoleUpdateObject.json --entityId <string> --roleId <string>	Update an entity role for a given entity.
EntityRoles
luis list entityRoles	Get all entity roles for a given entity.
Example
luis add example --in exampleLabelObject.json	Add a labeled example to the application.
luis delete example --exampleId <integer>	Delete the labeled example with the specified ID.
Examples
luis add examples --in exampleLabelObjectArray.json	Add a batch of labeled examples to the application.
luis list examples --skip <integer> --take <integer>	Return examples to be reviewed.
ExplicitListItem
luis add explicitListItem	Add a new item to the explicit list for the Pattern.Any entity.
luis delete explicitlistitem --entityId <string> --itemId <integer>	Delete the explicit list item from the Pattern.any explicit list.
luis get explicitlistitem --entityId <string> --itemId <integer>	Get the explicit list of the pattern.any entity.
luis update explicitlistitem --in item.json --entityId <string> --itemId <integer>	Update an explicit list item for a Pattern.Any entity.
ExplicitListItems
luis get explicitListItems --entityId <string>	Get the explicit list of the pattern.any entity.
Features
luis list features --skip <integer> --take <integer>	Get all the extraction features for the specified application version.
HierarchicalEntities
luis list hierarchicalEntities --skip <integer> --take <integer>	Get information about the hierarchical entity models.
HierarchicalEntity
luis add hierarchicalEntity --in hierarchicalModelCreateObject.json	Add a hierarchical entity extractor to the application version.
luis delete hierarchicalEntity --hEntityId <string>	Delete a hierarchical entity extractor from the application version.
luis get hierarchicalEntity --hEntityId <string>	Get information about the hierarchical entity model.
luis update hierarchicalEntity --in hierarchicalModelUpdateObject.json --hEntityId <string>	Update the name and children of a hierarchical entity model.
HierarchicalEntityChild
luis delete hierarchicalEntityChild --hEntityId <string> --hChildId <string>	Delete a hierarchical entity extractor child from the application.
luis get hierarchicalEntityChild	Get information about the hierarchical entity child model.
luis hierarchicalEntityChild <string>	Create a single child in an existing hierarchical entity model.
luis update hierarchicalEntityChild --in hierarchicalChildModelUpdateObject.json --hEntityId <string> --hChildId <string>	Rename a single child in an existing hierarchical entity model.
HierarchicalEntityRole
luis add hierarchicalEntityRole --in entityRoleCreateObject.json --hEntityId <string>	Add a hierarchical entity role.
luis delete hierarchicalEntityRole --hEntityId <string> --roleId <string>	Delete an entity role.
luis get hierarchicalEntityRole --hEntityId <string> --roleId <string>	Get all entity roles for a given entity.
luis update hierarchicalEntityRole --in entityRoleUpdateObject.json --hEntityId <string> --roleId <string>	Update an entity role for a given entity.
HierarchicalEntityRoles
luis list hierarchicalEntityRoles --hEntityId <string>	Get all hierarchical entity roles for a given entity.
Intent
luis add intent --in intentCreateObject.json	Add an intent classifier to the application.
luis delete intent --intentId <string> --deleteUtterances <boolean>	Delete an intent classifier from the application.
luis get intent --intentId <string>	Get information about the intent model.
luis update intent --in modelUpdateObject.json --intentId <string>	Update the name of an intent classifier.
IntentPatterns
luis list intentPatterns --intentId <string> --skip <integer> --take <integer>	Return patterns for the specific intent.
Intents
luis list intents --skip <integer> --take <integer>	Get information about the intent models.
luis suggest intents --intentId <string> --take <integer>	Suggest examples that would improve the accuracy of the intent model.
Models
luis list models --skip <integer> --take <integer>	Get information about the application version models.
CompositeEntityRoles
luis list CompositeEntityRoles --cEntityId <string>	Get all entity roles for a given entity.
Pattern
luis add pattern --in extractorCreateObject.json	Add patterns.
luis add pattern --in pattern.json	Add one pattern to the specified application.
luis add pattern --in patterns.json	Add a batch of patterns to the specified application.
luis delete pattern --entityId <string>	Delete the pattern with the specified ID.
luis delete pattern --patternId <string>	Delete the pattern with the specified ID.
luis get pattern --entityId <string>	Get information about the pattern with the specified ID.
luis update pattern --in pattern.json --patternId <string>	Update a pattern.
luis update pattern --in patternAnyUpdateObject.json --entityId <string>	Update a pettern.
PatternEntityRole
luis add patternEntityRole	Create an entity role for an entity in the application.
luis delete patternEntityRole --entityId <string> --roleId <string>	Delete an entity role.
luis get patternEntityRole --entityId <string> --roleId <string>	Get all entity roles for a given entity.
luis update patternEntityRole --in entityRoleUpdateObject.json --entityId <string> --roleId <string>	Update an entity role for a given entity.
PatternEntityRoles
luis get patternEntityRoles	Get all entity roles for a given entity.
Patterns
luis delete patterns --in patternIds.json	Deletes the patterns with the specified IDs.
luis update patterns --in patterns.json	Update patterns.
Permissions
luis add permissions --in userToAdd.json	Add a user to the allowed list of users to access this LUIS application. Users are added using their email addresses.
luis delete permissions --in userToDelete.json	Remove a user from the allowed list of users to access this LUIS application. Users are removed using their email addresses.
luis list permissions	Get the list of user emails that have permissions to access your application.
luis update permissions --in collaborators.json	Replace the current users access list with the one sent in the body. If an empty list is sent, all access to other users will be removed.
PhraseList
luis add phraselists --in phraselistCreateObject.json	Create a new phraselist feature.
luis delete phraselist --phraselistId <integer>	Delete a phraselist feature.
luis get phraselist --phraselistId <integer>	Get phraselist feature info.
luis update phraselist --in phraselistUpdateObject.json --phraselistId <integer>	Update the phrases, the state and the name of the phraselist feature.
PhraseLists
luis list phraselists --skip <integer> --take <integer>	Get all the phraselist features.
Prebuilt
luis add prebuilt --in prebuiltExtractorNames.json	Add a list of prebuilt entity extractors to the application.
luis delete prebuilt --prebuiltId <string>	Delete a prebuilt entity extractor from the application.
luis get prebuilt --prebuiltId <string>	Get information about the prebuilt entity model.
PrebuiltEntities
luis list prebuiltEntities	Get all the available pre-built entity extractors for the application.
PrebuiltEntityRole
luis add prebuiltEntityRole --in entityRoleCreateObject.json --entityId <string>	Create an entity role for an entity in the application.
luis delete prebuiltEntityRole --entityId <string> --roleId <string>	Delete an entity role.
luis get prebuiltEntityRole --entityId <string> --roleId <string>	Get all entity roles for a given entity.
luis update prebuiltEntityRole --in entityRoleUpdateObject.json --entityId <string> --roleId <string>	Update an entity role for a given entity.
PrebuiltEntityRoles
luis list rebuiltEntityRoles --entityId <string>	Get all entity roles for a given entity.
Prebuilts
luis list prebuilts --skip <integer> --take <integer>	Get information about the pre-built entity models.
Querylogs
luis list querylogs --appId <string>	Get the query logs of the past month for the application.
RegexEntities
luis list regexentities --skip <integer> --take <integer>	List all regex entity roles for a given entity.
RegexEntity
luis add regexEntity --in regexEntityExtractorCreateObj.json	Add a regex entity model to the application version.
luis delete regexentity --regexEntityId <string>	Delete a RegExEntity.
luis get regexentity --regexEntityId <string>	Get a RegExEntity record.
luis update regexEntity --in regexEntityUpdateObject.json --regexEntityId <string>	Update a RegExEntity.
RegexEntityRole
luis add regexentityrole --in entityRoleCreateObject.json --entityId <string>	Create a RegexEntityRole for an entity in the application.
luis delete regexEntityRole --entityId <string> --roleId <string>	Delete a RegExEntityRole.
luis get regexentityRole	Get a RegExEntityRole.
luis update regexEntityRole --in entityRoleUpdateObject.json --entityId <string> --roleId <string>	Update a RegExEntityRole.
RegexEntityRoles
luis list regexentityroles --entityId <string>	List RegExEntityRoles.
Settings
luis get settings --appId <string>	Get the application settings.
luis update settings --in applicationSettingUpdateObject.json --appId <string>	Update the application settings.
Status
luis get status	Gets the training status of all models (intents and entities) for the specified LUIS app. You must call the train API to train the LUIS app before you call this API to get training status. "appID" specifies the LUIS app ID. "versionId" specifies the version number of the LUIS app. For example, "0.1".
Sublist
luis add sublist	Add a list to an existing closed list.
luis delete sublist --clEntityId <string> --subListId <integer>	Delete a sublist of a specific closed list model.
luis update sublist --in wordListBaseUpdateObject.json --clEntityId <string> --subListId <integer>	Update one of the closed list's sublists.
UnlabeledUtterance
luis delete unlabeledutterance --in body.json --appId <string> --versionId <string>	Delete an unlabelled utterance.
UsageScenarios
luis list usagescenarios	Get the application available usage scenarios.
Version
luis clone version --in versionCloneObject.json --appId <string> --versionId <string>	Create a new version using the current snapshot of the selected application version.
luis delete version --appId <string> --versionId <string>	Delete an application version.
luis export version --appId <string> --versionId <string>	Export a LUIS application in JSON format.
luis get version --appId <string> --versionId <string>	Get the version info.
luis import version	Import a new version into a LUIS application.
luis publish version --appId <string> --versionId <version> --staging <true or false>	Publish a specific version of the application.
luis train version --applicationId <appId> --versionId <versionId>	Sends a training request for a version of a specified LUIS app. This POST request initiates a request asynchronously. To determine whether the training request is successful, submit a GET request to get training status. Note: The application version is not fully trained unless all the models (intents and entities) are trained successfully or are up to date. To verify training success, get the training status at least once after training is complete.
luis list versionsettings --appId <string> --versionId <string>	List the application version settings.
`luis update versionsettings --in appVersionSettingUpdateObjects.json --appId --useAllTrainingData <true	false>`
luis update version --in versionUpdateObject.json --appId <string> --versionId <string>	Update the name or description of the application version.
luis package version --appId <string> --versionId <string> --outputFolderPath <string>	Packages the trained application version in binary GZip format.
luis package slot --appId <string> --slotName <string> --outputFolderPath <string>	Packages the published application version in binary GZip format. slotName can either be PRODUCTION or STAGING.
Versions
luis list versions --appId <string> --skip <integer> --take <integer>	Get the application versions info.
AzureAccounts
luis list userazureaccounts --armToken <string>	List the user's LUIS Azure accounts.
luis list appazureaccounts --armToken <string> -- appId <string>	List the LUIS Azure accounts assigned to the application.
luis add appazureaccount --in accountToAdd.json --armToken <string> --appId <string>	Assigns a LUIS Azure account to the application.
luis delete appazureaccount --in accountToDelete.json --appId <string>	Deletes the assignment of the LUIS Azure account from the application.

How to Install into a node project

To save as a dependency into your node project:

npm install --save luis-apis

How to use

import * as msRest from "ms-rest-js";
import { LuisAuthoring, LuisAuthoringModels, LuisAuthoringMappers } from "luis-apis";
const options = { customHeaders: { "accept-language": "en-US" } };
const creds = new msRest.ApiKeyCredentials({ inHeader: { "Ocp-Apim-Subscription-Key": authoringKey } });
const client = new LuisAuthoring(creds);
const azureRegion = "westus";
client.apps.list(azureRegion, options).then((result) => {
  console.log("The result is:");
  console.log(result);
}).catch((err) => {
  console.log('An error ocurred:');
  console.dir(err, {depth: null, colors: true});
});

Nightly builds

Nightly builds are based on the latest development code which means they may or may not be stable and probably won't be documented. These builds are better suited for more experienced users and developers although everyone is welcome to give them a shot and provide feedback.

You can get the latest nightly build of LUIS from the BotBuilder MyGet feed. To install the nightly -

npm config set registry https://botbuilder.myget.org/F/botbuilder-tools-daily/npm/

Install using npm:

npm i -g luis-apis

To reset registry:

npm config set registry https://registry.npmjs.org/