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 :

This command is accessible by user with role as admin :

Command as team :

Project Management Command

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

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

Deployment Management Command

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

Environment Management Command

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

Channel Management Command

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

NLU Related Command

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

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