CLI Commands

ServisBOT CLI provides an interface for managing every aspect of your organization and bots.

Available Commands

  sb-cli alarm <command>              Used to perform actions associated with alarms
  sb-cli app <command>                Used to perform actions with a configured ServisBot app
  sb-cli auth-profile <command>       Used to perform actions associated with auth profiles
  sb-cli baas <command>               Used to perform actions associated with baas
  sb-cli blueprint <command>          Used to perform actions associated with blueprints
  sb-cli bot <command>                Used to perform actions associated with bots
  sb-cli chs <command>                Used to perform actions associated with chs
  sb-cli content <command>            Used to perform actions associated with CMS content
  sb-cli conversation <command>       Used to perform actions associated with conversations
  sb-cli email-template <command>     Used to perform actions associated with email templates
  sb-cli endpoint <command>           Used to perform actions associated with endpoints
  sb-cli entity <command>             Used to perform actions associated with entities
  sb-cli goal <command>               Used to perform actions associated with goals
  sb-cli goal-conversion <command>    Used to perform actions associated with conversions
  sb-cli intent <command>             Used to perform actions associated with bot intents
  sb-cli intent-insight <command>     Used to perform actions associated with intent insghts
  sb-cli job <command>                Used to perform actions associated with jobs
  sb-cli login <organization>         Used to authenticates our cli for use within your org
  sb-cli logs <command>               Used to perform actions associated with organization logs
  sb-cli metric <command>             Used to perform actions associated with metrics
  sb-cli missed-input <command>       Used to perform actions associated with missed input
  sb-cli missed-intent <command>      Used to perform actions associated with missed intents
  sb-cli ml-model <command>           Used to perform actions associated with Ml Models
  sb-cli monitoring <command>         Used to perform actions associated with monitoring
  sb-cli nlu <command>                Used to perform actions associated with NLU commands
  sb-cli pathway <command>            Used to perform actions associated with pathway
  sb-cli project <command>            Used to perform actions associated with projects
  sb-cli region <command>             Used to perform actions associated with regions
  sb-cli role <command>               Used to perform actions associated with roles
  sb-cli worker <command>             Used to perform actions associated with workers
  sb-cli sbapp <command>              Used to perform actions associated with Sb Apps
  sb-cli secret <command>             Used to perform actions associated with secrets
  sb-cli table <command>              Used to perform actions associated with tables
  sb-cli training <command>           Used to perform actions associated with intent training
  sb-cli user <command>               Used to perform actions associated with users
  sb-cli virtual-assistant <command>  Used to perform actions associated with virtual assistant

Profiles

It is possible to use profiles with the servisbot-cli as of version 3.1.0. Profiles allow you to use a –profile option on all commands to specifiy a particular user to use when running the command. This is typically useful when working with staging and production accounts.

sb-cli region set eu-1 --profile production
sb-cli login my-production-org --profile production

sb-cli region set eu-1 --profile staging
sb-cli login my-staging-org --profile staging

#staging and production profiles now available for all commands
sb-cli bot list --profile staging

sb-cli bot describe myProductionBot --profile production

login

Authenticates the servisbot-cli for use with your organization

bot

Create and manage your bots

sb-cli bot create <json>                           Creates a bot from inline JSON or a file                                            
sb-cli bot delete <bot_name>                       Deletes a bot by the given name                                                     
sb-cli bot delete-intents <bot>                    Deletes a particular bots intents                                                  
sb-cli bot describe <bot_name>                     Describes a bot with the given name                                              
sb-cli bot list                                    Lists all available bots                                                           
sb-cli bot update <json>                           Updates a bot from inline JSON or a file                                            
sb-cli bot patch <name> <json_path> <replacement>  Patch to a particular piece of a bot. The JSON Path is where the patch will apply   
sb-cli bot download <name>                         Downloads a bot definition, saves all assets related to that bot to the current directory.
sb-cli bot watch                                   Watches a directory containing a manifest for changes - uploads any modified definitions
sb-cli bot upload <directory>                      Uploads a bot definition using the directory provided                              
sb-cli bot publish <name>                          Publish Intents

Creating a bot

Bots requires a Name and at least one valid worker

Example for creating bots with required fields

 {
      "Name": "BotName",
      "Workers": [           
        {
          "Id": "abcdef1"
        }
      ]
   }

Example with all fields

{
    "Name": "BotName",
    "State": "RUNNING",
    "Timezone": "GMT +00:00 Dublin",
    "DisplayName": "SomeBotname",
    "Persona": "default-bot",
    "Description": "description",
    "SecureSession": true,
    "QuietTimeEnabled": true,
    "Id": "srn.bot.a8p4SHk-",
    "Workers": [
      {
        "Id": "abcdef1"
      }
    ],
    "NluManagementMode": "ServisBOT"
 }
  • NluManagementMode can be either ServisBOT or Remote

BaaS

Create and manage connectors

sb-cli baas create <json>     Creates a baas from inline JSON or a file path                                                           
sb-cli baas delete <alias>    Deletes a baas by the alias                                                                              
sb-cli baas describe <alias>  Describes a baas with the given alias                                                                 
sb-cli baas execute <json>    Executes a BAAS from inline JSON or a file                                                               
sb-cli baas list              Lists all available BAAS APIs                                                                            
sb-cli baas update <json>     Updates a BAAS from inline JSON or a file                                                               

Creating a BaaS

These are the required fields for creating a BaaS through the CLI

{
  "Alias": "N3F7Yq_1St",
  "Endpoint": "https://www.bing.com",
  "RequestMapping": {},
  "ResponseMapping": {},
  "Headers": {},
  "Method": "GET",
  "Body": {}
}

Example with all fields

{
    "Alias": "N3F7Yq_1St",
    "Endpoint": "https://www.bing.com",
    "RequestMapping": { "key": "mapping" },
    "ResponseMapping": { "key": "mapping" },
    "Headers": { "key": "headers" },
    "Method": "GET",
    "Body": { "key": "body" }
}

endpoint

Create and manage endpoints

sb-cli endpoint create <json>                              Creates an endpoint from inline JSON or a file
sb-cli endpoint delete <address>                           Deletes an endpoint by the given address
sb-cli endpoint describe <address>                         Describes an endpoint with the given address
sb-cli endpoint list                                       Lists all available endpoints
sb-cli endpoint update <json>                              Updates an endpoint from inline JSON or a file
sb-cli endpoint patch <address> <json_path> <replacement>  Patch to a particular piece of an endpoint. The JSON Path is where the patch will apply

Creating an Endpoint

These are the required fields for creating an endpoint through the CLI

 {
   "Address": "SomeAddress",
   "Name": "NiceName",
   "Status": "online",
   "TargetBotReference": "botName",
   "InboundBotReference": "botName",
   "OutboundBotReference": "botName",
   "Useragent": "userAgent",
   "AllowedDomains": [],
 }

Additionally, a Style property can be assigned to theme the bot, or an engagement adapter can be set

worker

Create and manage workers.

sb-cli worker create <json>                         Creates a worker from inline JSON or a file                                        
sb-cli worker delete <worker_name>                  Deletes a worker by the given name                                                 
sb-cli worker describe <worker_id>                  Describes a worker with the given name                                          
sb-cli worker update <json>                         Updates a worker from inline JSON or a file                                        
sb-cli worker patch <id> <json_path> <replacement>  Patch to a particular piece of a worker. The JSON Path is where the patch will apply
sb-cli worker cycle-detection <worker_id>           Performs cycle detection on the given worker                                      

Creating a Worker

Creating a worker requires at least the fields Name, Type, Enabled, Data, Config

 {
    "Name": "SweetName",
    "Type": "r2-filter-worker",
    "Enabled": true,
    "Data": {},     
    "Config": {},
 }

Example of a more advanced worker definition

{
  "Name": "filterWorker",
  "Description": "Filter Worker",
  "Enabled": true,
  "Type": "r2-filter-worker",
  "Config": {
    "Avatar": "default-bot"
  },
  "Data": {
    "pageEvents": [
      {
        "alias": "hit-api",
        "actions": [
          {
            "type": "baas",
            "alias": "wellBaaas"
          },
          {
            "type": "baas",
            "alias": "wellBaaas1"
          }
        ]
      },
      {
        "alias" : "send-something",
        "match" :{
          "path": "$.user.name",
          "value": "botty"
        },
        "actions" : [
          {
            "type": "message",
            "value": "hello there, botty"
          }
        ]
      },
      {
        "alias": "send-something",
        "actions": [
          {
            "type": "message",
            "value": "hello there"
          }
        ]
      },
      {
        "alias": "trigger-flow",
        "actions": [
          {
            "type": "flow",
            "value": {
              "type": "r2-avalanche-worker",
              "deferRelease": true,
              "id": "d2ccd1dc-3c51-4ec1-be29-bf6588602b48"
            }
          }
        ]
      }
    ]
  }
}

blueprint

Create bots from Blueprints

sb-cli blueprint list               Lists all available blueprints                                                                     
sb-cli blueprint build <json>       Builds a from a blueprint using inline JSON or a file                                              
sb-cli blueprint build-interactive  Builds a from a blueprint interactively

conversation

Monitor Conversations

sb-cli conversation export <startDate> <endDate>                    Begin export of conversation data for your Organization between the date range supplied
sb-cli conversation export-status <exportId>                        Check the status of a given export job
sb-cli conversation export-download <exportId> [-o <outputFile>]    Download the results of a given export job

secret

Configure organization secrets

sb-cli secret create <json>                     Creates a secret from inline JSON or a file                                            
sb-cli secret delete <srn>                      Deletes a secret by the given srn                                                      
sb-cli secret describe <srn>                    Describes a secret with the given Srn                                               
sb-cli secret list                              Lists all available secrets                                                            
sb-cli secret update <json>                     Updates an secret from inline JSON or a file                                           
sb-cli secret create-interactive                Creates a secret interactively                                                        
sb-cli secret create-external-id <secret_name>  Creates a external id                                                               

Creating a Secret

These are the bare minimum required fields for creating a secret of type secretdoc.

{
  "Name": "my-secret",
  "Type": "secretdoc",
  "Value": {
    "Some": "data"
  },
}

These are the bare minimum required fields for creating a secret of type secret.

{
  "Name": "my-secret",
  "Type": "secret",
  "Value": "some data",
}

goal

View and export goals

sb-cli count <goal>      Get goal counts                          [aliases: c]
sb-cli export bot <bot>  Exports goals by BotName                [aliases: eb]

Exporting by Bot

sb-cli goal export bot <bot>

To convert this export to CSV, add a few parameters to clean up the output: -q, format into csv -o csv, and > filename.csv to push the results to a file.

sb-cli goal export bot <bot> -q -o csv > filename.csv

Exporting by Goal

sb-cli goal count <goal>
Parameter Options Default Description
<goal> NA Required The bot you want to export
–groupBy, or –gb bot bot What you want to group by
–start, -s NA “2019/4/3” The time to begin searching from in the form YYYY/MM/DD
–end, -e NA “2019/4/3” The time to finish searching to in the form YYYY/MM/DD

goal-conversion

Group goal interactions together

sb-cli goal-conversion create <json>                           Creates a conversion from inline JSON or a file path                    
sb-cli goal-conversion describe <bot_name> <conversion_name>   Describes a conversion for a particular bot                          
sb-cli goal-conversion list                                    Get a list of conversions                                               
sb-cli goal-conversion delete <bot_name> <conversion_name>     Deletes a conversion by the name for a particular bot                   
sb-cli goal-conversion update <json>                           Updates a Conversion from inline JSON or a file                         
sb-cli goal-conversion calculate <bot_name> [conversion_name]  Describes all conversions or a particular conversion for a given bot

virtual-assistant

Create and manage virtual assistants

sb-cli virtual-assistant create <json>                                 Creates a virtual assistant from inline JSON or a file          
sb-cli virtual-assistant delete <virtual_assistant_name>               Deletes a virtual assistant by the given name                   
sb-cli virtual-assistant describe <virtual_assistant_name>             Describes a virtual assistant with the given name            
sb-cli virtual-assistant update <json>                                 Updates a virtual assistant from inline JSON or a file          
sb-cli virtual-assistant list                                          Lists all available virtual assistants                          
sb-cli virtual-assistant train <virtual_assistant_name>                Trains a virtual assistant with the given name                  
sb-cli virtual-assistant dry-run <virtual_assistant_name> <utterance>  Performs a dry run routing attempt against a VA                
sb-cli virtual-assistant upsert-endpoint <virtual_assistant_name>      Upserts the inference endpoint associated with a virtual assistant
sb-cli virtual-assistant delete-endpoint <virtual_assistant_name>      Deletes the inference endpoint associated with a virtual assistant

region

Set your CLI region

sb-cli region set <region>  Sets the region to be used by the ServisBot CLI. Available regions: eu-1 and us1
sb-cli region show          Returns the region currently used by the CLI

metric

Pull data exports

sb-cli metric transaction <range>  Get metric transactions                                                                             
sb-cli metric response-time        Get metric response time                                                                           

user

Manage users and permissions

sb-cli user update <json>     Updates a user from inline JSON or a file                                                                
sb-cli user create <json>     Creates a user from inline JSON or a file                                                                
sb-cli user describe <email>  Describes a user for the given email                                                                     
sb-cli user list              Lists all available user                                                                                 
sb-cli user delete <email>    Deletes a user for the given email                                                                     

role

View roles and permissions

sb-cli role list  Lists all available roles

intent

Create and manage intents

sb-cli intent import <utterances> <actions>   Begin import of intents for a bot                                                        
sb-cli intent create <json>                   Creates a intent from inline JSON or a file path                                         
sb-cli intent update <json>                   Updates an intent from inline JSON or a file                                             
sb-cli intent describe <bot> <alias>          Describes an intent                                                                   
sb-cli intent delete <bot> <alias> <version>  Deletes a particular intent                                                              
sb-cli intent list <bot>                      Get a list of intents for a bot                                                          
sb-cli intent export <bot>                    exports the intents for the given bot.                                                

job

Check Job Statuses

sb-cli job status <srn>  Gets the status of a job                                                                                   

missed-input

Monitor missed-input

sb-cli missed-input export  Exports missed input                                                                                       

logs

Watch logs

sb-cli logs watch  Watches logs for your organization                                                                                  

auth-profile

Setup and manage auth profiles

sb-cli auth-profile create <json>             Creates an auth profile from inline JSON or a file path                                  
sb-cli auth-profile describe <alias>          Describes an auth profile from the given alias                                        
sb-cli auth-profile list <limit> [nextToken]  Lists auth profiles, limited to the supplied limit and paginated by the supplied token   
sb-cli auth-profile delete <alias>            Deletes an auth profile with the given alias                                           
sb-cli auth-profile update <json>             Updates an auth profile with the given alias from inline JSON or a file path             

training

Manage training of intents

sb-cli training create-changeset <json>          Creates a changeset from params or a file
sb-cli training apply-changeset <bot> <alias>    Applies a changeset
sb-cli training describe-changeset <bot> <alias> Describes a changeset
sb-cli training classification-report            Generates a User Input classification report
sb-cli training list-recommendations             Returns recommendations for a resource type
  <resourceType> <resourceName>                  and name

Creating and applying changeset allows users to add utterances to an existing or new intent. To create a changeset the json should be of the form:

{
  "Bot": "BotName",                             /*Required*/
  "Alias": "MyChangeset",                       /*Required*/
  "Description": "My First Changeset",          /*Required*/
  "Path": "/path/to/file/file.csv",             /*Required*/
}

An example of the changeset file is as follows

Utterance,Suggested Intent,Action
"I need to pay off a loan","loan_help","ADD_UTTERANCE"
"I need some help","support","CREATE_INTENT"
"My loan is paid off","loan_help","REMOVE_UTTERANCE"

The valid options for Action are ADD_UTTERANCE, CREATE_INTENT and REMOVE_UTTERANCE

Once you apply a changeset, it cannot be deleted.

Generating a classification report

Example of specifying the bot and day for the classification report

sb-cli training classification-report -b my-bot-name -d "2020/03/03"
  • Please note the format of the date is ‘YYYY/MM/DD’ and must be surrounded in quotes.
  • If you do not specify a day, today’s date will be used by default.