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 kata-cli@x.y.z

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 support@kata.ai. 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 :)