Kata-CLI Overview and Command Reference

Kata Command Line Interface (Kata CLI) is a tool for creating bot with Kata Markup Language (Kata ML) and helps managing the bots with command line/shell of various operating systems.

Installing Kata-CLI

Install Kata-CLI using the npm package manager.

npm install -g kata-cli

This is the preferred method to install Kata-CLI in a global mode, as it will always install the most recent stable release.

Changelog

For details about changes between versions, and information about updating from previous releases, see the Changelog

Upgrade Kata-CLI version

To check your installed Kata-CLI version, use this command:

➜   kata --version

Please refer to the full descriptions on Changelog to check the latest version. Make sure to update Kata-CLI to the latest stable version before doing some fun with your Bot with this command:

➜  npm i -g [email protected]

you can add @version-number to be exact.

Command Overview

Use kata --help into your command line to find out the list of commands offered by Kata-CLI with a short description. The new command in Kata-CLI is that with asterisk (*).

User Management

The list of command below is accessible by user with role as user :

Commands | Functionalities --------------------- | ------------------------------------------------------------------------------------------- kata login [options] | the parameter options can be user or team kata whoami | to see the current user login informations kata change-password | to change user's password kata create-team <teamName> | to create team kata logout | to logout from the platform () kata forgot-password <userName> | to set new password when user forgot () kata list-team | to list user's team (*) kata list-team-user [teamName] | to list user's team member

This command is accessible by user with role as admin :

Commands | Functionalities --------------------- | ------------------------------------------------------------------------------------------- kata create-user | to set spesific role and create user

Command as team :

Commands | Functionalities --------------------- | ------------------------------------------------------------------------------------------- kata add-member <userName> [options] --admin | to assign user as the teammember kata remove-member <userName> | to remove member from the team kata switch <roleType> [userName or teamName] | to switch between user and team role. Parameter must be user or team.

Project Management Command

The new commands (on version 2.4.0) to manage Project are those with asterisk (*).

Commands | Functionalities --------------------- | ------------------------------------------------------------------------------------------- kata create-project | to create a project kata list-project | to display current projects that you have kata select-project | to select project that you want to use, any bot operation will be related to that project () kata delete-project [projectName] | to delete project () kata update-project [projectName] | to update project details

Bot, Deployment, Environment and Channel Management Command

Bot Management Command

Here are list of commands to manage Bot, those with asterisk (*) are the the new commands on version 2.4.0

Commands | Functionalities --------------------- | ------------------------------------------------------------------------------------------- () kata view-config | to view user configurations kata init <botName> | to initialize the bot kata revisions | to list the revisions of the bot kata list-bots | to list the bots kata push | to push the bot revision kata pull [revision] | to pull the bot with specified name and version kata remove-bot | to delete selected bot kata test [fileName] | to run a test for the bot kata console [revision] | to converse with the bot, updated features: user can choose certain environment console kata drop <botName> | to drop bot kata set <property> <value> | to set configuration setting on Kata-CLI () kata errors | to list error log from a bot

Deployment Management Command

Here are list of commands to manage Deployment, those with asterisk (*) are the the new commands on version 2.4.0

Commands | Functionalities --------------------- | ------------------------------------------------------------------------------------------- kata create-deployment | to create a deployment kata list-deployment | to list deployments (*) kata rollback-deployment <version> | to rollback to certain deployment

Environment Management Command

Here are list of commands to manage Environment, those with asterisk (*) are the the new commands on version 2.4.0

Commands | Functionalities --------------------- | ------------------------------------------------------------------------------------------- kata create-environment <slug> | Create an environment on the selected project kata list-environment | List environments of the selected project kata update-environment <newDeploymentVersion> | Update an environment of the selected project

Channel Management Command

Here are list of commands to manage Channel, those with asterisk (*) are the the new commands on version 2.4.0

Commands | Functionalities --------------------- | ------------------------------------------------------------------------------------------- () kata add-channel [options] <channelName> | Create a channel with channelName on the selected environment () kata update-channel [options] <channelName> | Update a channel on the selected environment kata list-channel | List channels of the selected environment kata remove-channel <channelName> | Remove the channel named channelName from the selected environment

NLU Related Command

Here are list of commands to manage NLU, those with asterisk (*) are the the new commands on version 2.4.0

Commands | Functionalities ---------|----------------- kata nl-init | to initialize nl definition kata nl-push | to push nl changes kata nl-pull | to pull nl changes from remote kata nl-train [options] | to train a sentence or a batch of sentences. [options] can be -f <trainPath/fileName.txt> kata nl-predict [options] | to predict a sentence. [options] can be [-f <predictPath/fileName.txt>] kata list-profiles | to list all profiles kata nl-snapshot | to save the nlu snapshot () kata nl-list-training --page=<pageNumber> | to list the training sentences () kata nl-list-prediction --page=<pageNumber> | to list the prediction log () kata nl-list-revision | to list the revision () kata nl-issue-token | to (re-)issue token

Outdated Commands on Kata-CLI

Here are the list of outdated commands on version 2.4.0, please refer to Changelog for the details.

List of Deprecated Command:

• kata add-channel <channelName>
• kata edit-channel <channelName>
• kata config-view
• kata add-member

List of Permanently Deleted Command:

• kata deploy <name> [version]
• kata session-get <id> [deploymentId]
• kata session-create <id> [deploymentId]
• kata session-update <id> [deploymentId]
• kata session-delete <id> [deploymentId]
• kata timestamp

Workflow

We hope that you can get a smooth experience in working with Kata-CLI by following several best practice steps:

Project Workspace

In Kata-CLI upto 2.0 version, we introduce Project Environment on the top of the Bots, Deployment, Environment, NLU and CMS. Hence, before running Kata-CLI main command, such as: kata init,kata push, kata console., user have to initiate and define the Project that they are going to work on.

1. Create the Project

Welcome to your project workspace. In this documentation, you may find the term project and bot is used interchangeably, since a bot belongs to a project.

For the first step, create folder where we're going to wrap our project in. Then let's create our first project, where a bot, deployments, environments and channels are attached to.

➜ kata create-project
? Project name: your-project-name
? Timezone (UTC) 7
? Project description: your-project-desc
? NLU Language id
? Is private Nlu? Yes
  Project "your-project-name" (5c9ea2b9-ab79-4aa8-aaa0-a831bbb175de) is successfully created

Voila, your first project is there.

If you already have an existing project that you're gonna be working on, you have to select the project first. To show the list of your project, run this command:

➜ kata select-project

2. Create the Bot

Once the project is selected, it is the time to build the bot using this command:

➜ kata init <your-bot-name>

This command will generate a bot.yml under the project. This file contains a simple hi-bot template written in Kata Markup Language (Kata-ML) schema, as the first revision of your bot.

Run this command to see the list of bot revisions:

➜ kata revisions

3. Push your bot changes

Customize your bot schema on bot.yml file, then push the bot to apply the changes:

➜ kata push
  Push Bot Success. Revision : 6bb61b7

4. Test a conversation with your bot

Once you pushed the latest revision of your bot, meaning that you are ready to test a conversation with the bot. Run this command on your terminal:

➜ kata console

We'll enter the virtual environment (node shell) to do a chatting simulation with the bot.

  your-bot-name>text("hi")
  { messages:
    [ { type: 'text',
        content: 'hi',
        id: 'd5a1a010-fb60-42cf-96c8-c648fc557443',
        intent: 'greeting',
        attributes: {} } ],
    responses:
    [ { type: 'text',
        content: 'hialo!',
        action: 'text',
        id: '1f7caf54-ee6f-4aa6-9696-bdcced9e406a',
        refId: 'd5a1a010-fb60-42cf-96c8-c648fc557443',
        flow: 'hello',
        intent: 'greeting' } ],
    session:
    { id: 'test~from~console',
      states: {},
      contexes: {},
      history: [],
      current: null,
      meta: { lastFlow: 'hello', lastState: 'greet', end: true },
      timestamp: 0,
      data: {} },
    duration: 86 }
  your-bot-name>
  (To exit, press ^C again or type .exit)

Kata-CLI will create a session that alive along the conversation and generate a .katasession file in your home directory for further debugging (if needed).

To view your current session, you can either run this command:

➜  cat ~/.katasession
{"id":"test~from~console","states":{},"contexes":{},"history":[],"current":null,"meta":{"lastFlow":"hello","lastState":"other","end":true},"timestamp":0,"data":{}}%

or this command, for a better JSON alignment:

➜   kata console
    your-bot-name>current()
      {
        id: 'test~from~console',
        states: {},
        contexes: {},
        history: [],
        current: null,
        meta: { lastFlow: 'hello', lastState: 'other', end: true },
        timestamp: 0,
        data: {}
      }

Congratulations that you finish your first revision of the bot. Now it is the time to deploy your bot.

Deploy your Project

Follow these following steps to deploy your project to messaging channels.

1. Create a Deployment

Create a new deployment version using these command. If you do not specificy the deployment types (major/minor/patch), it will automatically create a deployment with patch.

➜  kata create-deployment [deploymentType]

2. Create and Update Environment

After having the deployment, we need to create an environment. Environment works like tier in which a your bot is deployed and executed. We provide three stages of environments: Development, Staging, Production.

➜  kata create-environment <slugName>

Your freshly created environment will auto-select the latest deployment version.

If you already have environment, you can just simply update it with the newer deployment version using this command:

➜  kata update-environment <newDeploymentVersion>

3. Create Channel

Let's create messaging channel under environment. The steps are: type the command to create channel below, then choose the environment where it belongs to.

➜  kata create-channel <channelName>

(*) Notes: Previously, the command to create channel is: kata add-channel <channelName> From this version above, the command is changed to: kata create-channel <channelName>

Integrate with NLU

An NLU must be under a project. Therefore, we need to define a project, before we create an NLU.

1. Initialize NLU Project

It would create a new file nlu.yml in which the nlu structure can be defined.

# initialize a nlu project
➜  kata nl-init

2. Push NLU

To use push command to create and update the NLU

# push current nlu project
➜  kata nl-push

3. List Profiles

To list all profiles

➜  kata list-profiles

4. Train NLU

To train a nlu.

➜  kata nl-train [-f <trainPath/filename.txt>]
➜  kata nl-train [-s <sentence>]

5. Predict Sentences with NLU

➜  kata nl-predict [-f <trainPath/filename.txt>]
➜  kata nl-predict [-s <sentence>]

Contributing

Is something missing/incorrect? Please let us know by contacting [email protected]. If you know how to fix it straight away, don’t hesitate to create a pull request on this documentation’s GitHub repository by following these steps:

1. Fork this repository
2. Name your branch with prefix feature/ if you added new feature, hotfix/ if you fixed some bugs
3. Code, and dont forget to add test after added new feature
4. Commit your branch and pull request to base develop branch

Happy contributing :)