• ServisBot CLI
  • Set up
    • Getting Started
    • Authenticate
  • Commands
  • Getting help
  • Global Options
  • Enable command completion
  • Developer Notes
  • How do I update the Changelog?
  • What are the Changelog rules?
  • How do I release the cli?
  • Troubleshooting
    • 1. aesprim-browser.js: Permission denied
    • 2. npm ERR! It is likely you do not have the permissions to access
    • Env Vars
  • Using the cli programmatically

ServisBot CLI

Enterprise developer entry point into ServisBot

Set up

Getting Started

1. Install npm module globally on your machine. npm install -g @servisbot/servisbot-cli

   • For any installation issues regarding permissions see Troubleshooting

2. Authenticate with the CLI

Authenticate

Run the following command:

$ sb-cli login <organization>

The CLI will then ask for an email and a password associated with this organization. All future commands will be run using these credentials. If MFA is enabled for your user you will be asked for your MFA token on login, you will receive a sms to the mobile number on your account

Commands

Click on each command to see all the sub-commands and the relevant documentation.

• sb-cli login - Authenticates the servisbot-cli for use with your organization
• sb-cli bot - Used to perform actions associated with bots
• sb-cli baas - Used to perform actions associated with baas
• sb-cli endpoint - Used to perform actions associated with endpoints
• sb-cli worker - Used to perform actions associated with workers
• sb-cli blueprint - Used to perform actions associated with blueprints
• sb-cli region - Used to perform actions associated with regions
• sb-cli conversation - Used to perform actions associated with conversations

Getting help

While using the CLI, you can run --help to obtain further instructions on how to use a command.

For example, the commands below are all valid and will provide meaningful information:

sb-cli --help
sb-cli bot --help
sb-cli worker update --help

Global Options

With --verbose the CLI will return detailed logging and stacktraces on command execution. This is particularly valuable when running into issues and/or errors.

Enable command completion

To enable autocompletion of commands, you can run sb-cli completion and concat the generated script to your .bashrc or .bash_profile; e.g.

sb-cli completion >> ~/.bashrc

sb-cli completion >> ~/.bash_profile

sb-cli completion >> ~/.zshrc

Developer Notes

NOTE: for non-production environments, you will need to setup a local config file: ~/.servisbot.config. A sample file is:

{
  "region":"eu-1"
}

How do I update the Changelog?

• Open the CHANGELOG.md file
• At the top of the file, you'll find the Next Release section
• Add a bullet point to that list with a brief summary of your changes
• Commit/push your change!

What are the Changelog rules?

• Any new functionality should be added to the changelog
• You should note when you bump the sb-sdk but you also need to note what the functionality changes are
  • A "bumped sdk to 1.2.3" with no further information will not be accepted

* bumped sb-sdk to 1.2.3
  * VAs can now disable their bots
  * Workers can generate their own IDs

• Only change the Next Release section when adding functionality, see below for the release process
• The Changelog, this README, and the code you write are all public. Be helpful to end users with your entries.

How do I release the cli?

• Open a PR and grab the items from Next Release section and put them into a new version entry, please note, the date format is yyyy/MM/dd e.g.

## Next Release

## 7.8.0 (2020/10/19)
* Bumped sb-sdk to 10.0.1
  * Changed positional name and description on `lift-shift` command from `exportedJson` to `filePath`
  * Added support to `lift-shift` command to handle Rasa v2 projects

• opsbot request servisbot-cli 1.2.3
• Add the Changelog PR in a thread of the release requests response
  • Only the Changelog should be changed in this PR
• The person doing this release, approves AND merges the PR if happy
• The cli is released by the same person

Troubleshooting

1. aesprim-browser.js: Permission denied

sh: 1: cannot create generated/aesprim-browser.js: Permission denied

• This may be an npm cache error and using npm cache clean will fix this for you.
• If this does not work, it may be a permissions issue, see below.

2. npm ERR! It is likely you do not have the permissions to access

Permission errors are usually produced when installing a package using npm as a non root user and npm has been installed as root

npm ERR! The operation was rejected by your operating system.
npm ERR! It is likely you do not have the permissions to access this file as the current user

It is best practice to install npm as a non-root user, however, if you are unable to do so and are receiving the error above, you can provide the --unsafe-perm=true flag and run npm with the sudo command , this is not recommended in most situations.

unsafe-perm
  Default: false if running as root, true otherwise
        Type: Boolean
  Set to true to suppress the UID/GID switching when running package scripts. If set explicitly to false, then installing as a non-root user will fail.

• see unsafe-perm for more details.

Depending on your system, you may be able to use flag --unsafe-perm=true without the sudo command. Again, this is not recommended but your installation may force you to do this

• May be required when installing in a docker container and using the FROM node in a Dockerfile, as npm in docker is installed as a root user. You can avoid this if you install npm as a non-root user, but is a little excessive if you are only spinning up the container for short-term uses

• Unless you are fully aware why you need to use --unsafe-perm or sudo to install the @servisbot/servisbot-cli we do not recommend using it as there should be no need to run this module as a root user.

Env Vars

• SB_DISABLE_UPDATE_CHECK - set to "true" if using the cli in an automation context

Using the cli programmatically

To use the cli in a node script simply import @servisbot/servisbot-cli and initialize the cli with an object containing a username, password, organization and region. You will be logged in and returned an object containing commands and their sub-commands that the logged in user has access to. Most commands will return a json object, others will return a list of strings.

const SbCli = require('@servisbot/servisbot-cli');
      
const params = {
    password: process.env.password,
    organization: process.env.organization,
    username: process.env.username,
    region: process.env.region
};

// Init the cli with params to be logged in and returned an object of commands
const sbCli = await SbCli(params);

// Show commands
console.log(sbCli);

// Creating items
const worker = {
    "Name": "CliWorker",
    "Type": "r2-filter-worker",
    "Enabled": "true",
    "Data": {},
    "Config": {}
};
const wrkResponse = await sbCli.worker.create({json: JSON.stringify(worker)});

// Listing items
const workers = await sbCli.worker.list();

Using with different orgs or different users on the same org

const SbCli = require('@servisbot/servisbot-cli');
      
const paramsOrgOne = {
    password: process.env.PASSWORD_ONE,
    organization: process.env.ORGANIZATION_ONE,
    username: process.env.USERNAME_ONE,
    region: process.env.REGION_ONE
};

const paramsOrgTwo = {
    password: process.env.PASSWORD_TWO,
    organization: process.env.ORGANIZATION_TWO,
    username: process.env.USERNAME_TWO,
    region: process.env.REGION_TWO
};


// Init the cli with params to be logged in and returned an object of commands
const sbCliOrgOne = await SbCli(paramsOrgOne);
const sbCliOrgTwo = await SbCli(paramsOrgTwo);

// You can then do any commands then 
const botsOrgOne = await sbCliOrgOne.worker.list();
const botsOrgTwo = await sbCliOrgTwo.worker.list();

ServisBot, Copyright 2020