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.

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.

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

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.

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 (*).

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

This command is accessible by user with role as admin :

Command as team :

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

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

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

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

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

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

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

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

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.

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

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

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

➜ kata push
  Push Bot Success. Revision : 6bb61b7

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.

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

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]

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>

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>

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

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

# initialize a nlu project
➜  kata nl-init

To use push command to create and update the NLU

# push current nlu project
➜  kata nl-push

To list all profiles

➜  kata list-profiles

To train a nlu.

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

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

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 :)