@nimbella/commander-cli

Commander CLI

Commander CLI is a Nimbella Commander development tool that allows you to create, run & publish your serverless functions as commands that can run in Slack, Microsoft Teams, and Mattermost.

Here's a glimse of what you can achieve with Commander CLI:

• Run Slash commands, built for messaging platforms, from your terminal.
• Login to different Commander clients (Slack, Mattermost, Teams) directly from the terminal.
• Bootstrap Command Set development (with auto generation of the necessary files and code templates).
• Install Command Sets from your local machines onto messaging platforms.

Commander introduces the following terminology:

• Command: A serverless function that executes some business logic and returns output formatted for a messaging platform.
• Command Set: A set of related commands grouped together for easy installation and sharing.

Visit our website to learn more about Commander and how it can help you extend your messaging environment with new and rich APIs.

The following guide provides details for getting started using the Commander CLI.

Contents

• Quick Start
• Install a Command Set
• Develop a Command Set
• Login to Your Messaging Platform
• Install a Local Command Set
• Publish a Command Set
• Invoke Commands Using API
• Support
• License

Quick Start

The Nimbella CLI provides a convenient command-line and REPL-interface for Commander. Please follow this guide to install the Nimbella CLI.

You need to run the following login command before you can use the Nimbella CLI.

$ nim login

Run nim commander help to learn how to use Commander from your terminal.

$ nim commander help
Commander CLI
A CLI to interact with Commander from your terminal.

USAGE
$ nim commander - launch Commander REPL
$ nim commander help - display help for Commander CLI
$ nim commander docs - open documentation
$ nim commander <command> [command_params/command_options] - run commander commands

REPL Commands
exit - exit the repl
clear - clear the repl
help - display help in repl
history - show recently executed commands

Commander Commands
command_create <command> [<parameters>] ... - Creates a command & opens online source editor
csm_install <command-set> - Install from Nimbella Command Set Registry: https://github.com/nimbella/command-sets
csm_install /path/to/your/command-set - Install a local Command Set
csm_install github:<owner>/<repository> - Install a Command Set hosted on GitHub

Please refer https://nimbella.com/resources-commander/reference to learn about Commander commands.

Install a Command Set

There are two ways to interact with Commander from the terminal. The first is the read–eval–print loop or REPL interface and the second is executing Commander commands as subcommands of nim commander (ex: nim commander csm_list). We will use the REPL to show you how to install a new Command Set.

Run the following to enter the REPL:

$ nim commander

Note: It may take up to 30 seconds to complete this command the first time you run it, as the system may need to perform some configuration to enable your Nimbella account for Commander.

Command Sets are installed using the csm_install command followed by the name of the Command Set. For example, to install the dig Command Set, execute the command shown below.

nc> csm_install dig

The output will resemble what is shown below.

nc> csm_install dig
Installed dig command-set for app nc, containing the following commands:
dig: Perform DNS queries.

The Unix dig command allows you to query DNS records for hostnames. Now we can run it as a Command as in the example below.

nc> dig nimbella.com A
nimbella.com Type: A TTL: 19 IP: 157.245.130.6

Checkout Nimbella Command Set Registry for more Command Sets.

Develop a Command Set

The Nimbella CLI helps you develop and test Command Sets for Commander directly from your laptop or personal machine.

Let's kick start the development process with command_set create. The command requires an additional parameter which is the name of the Command Set.

After you've run the command in the REPL and answered the questions, a directory is created with all the necessary files generated so you can get started.

The directory structure for the greet example will be resemble the following:

greet
├── README.md
├── commands.yaml
└── packages
    └── greet
        ├── hello.js
        └── hola.js

The template generation includes sample code, so you can immediately install the Command Set and try it out. The same project contains two commands, one called hello and the other called hola. Try running the commands shown next. Each command runs a function with returns a standard place holder response.

You may edit the sample code to implement your desired logic for each command. Each command corresponds to a function in the corresponding file. The function accepts certain parameters which may be used in the code. For example, the change below will modify the command hello to greet a user by name. To make this change, edit greet/packages/greet/hello.js using your favorite code editor, and edit the text property inside the object returned by _command.

return {
    response_type: 'in_channel', // or `ephemeral` for private response
-    text:
-      'This is a default response for a newly created command with text: ' +
-     commandText,
+    text: `Hello, ${params.name}!`,
  };

For this to take effect in Commander, we need to update the code using csm_update.

Congrats! You now know how to develop a Command Set using the Commander CLI. Try to modify hola now on your own.

Login to Your Messaging Platform

You need a cli-login token to login to your messaging platform (Slack, Mattermost, Teams) from Commander CLI.

Run /nc app_info in your messaging platform to obtain the cli-login token.

After you've obtained the token, run the below command with your token in Commander CLI to login to your messaging platform.

nc> client login <your_login_token>

You can also switch the login context between CLI and messaging platform by running client switch.

nc> client switch

Install a Local Command Set

In this section, you will learn how to install a Command Set whose code is on your local machine.

You need to provide the location of the Command Set to csm_install to install it.

nc> csm_install /your/path/to/greet

Note: even relative paths work.

That’s it. You can now run the commands available in your locally developed command set from the Commander CLI.

To be able to access these commands from messaging platforms, you need to run the same command, but you should do it after you've logged in to your messaging platform from Commander CLI.

Publish a Command Set

There are two options to distribute and share a Command Set that you develop: via your GitHub Repository or via the Nimbella Command Set Registry.

1. Publish as a GitHub Repository

   Create a GitHub repository with your code and make sure commands.yaml is at the root of the repository.

   To install Command Sets that are published as GitHub repositories, you need to run /nc csm_install github:<your_github_username>/<repository_name>. Ex: /nc csm_install github:nimbella/greet

2. Publish to Nimbella Command Set Registry

   Make a Pull Request to our registry with your Command Set. See our contribution guide on the registry to learn more.

   After your Command Set is in the registry, you can install it by running: /nc csm_install <command_set_name>. Ex: /nc csm_install greet

Invoke Commands Using API

Any command of a Command Set that's installed can be invoked programmatically.

Use api_get to get an endpoint for a command.

The output will also include the credentials required to execute the command. I've redacted them here.

nc> api_get hello Nimbella
Command parameters:
    {
      "user_id": "...",
      "team_id": "...",
      "command": "/nc",
      "syncRequest": "true",
      "text": " hello Nimbella"
    }

    You can invoke the command with nim by running:

    nim action invoke --auth=...:... /nc/portal/cli-gateway --result  -p __ow_headers '{"accept": "application/json", "content-type": "application/x-www-form-urlencoded", "user-agent": "commander-cli" }' -p command /nc -p syncRequest '"true"' -p text ' hello Nimbella' -p user_id ... -p team_id ...

    You can also invoke the command with curl by running:

    curl -H "Content-Type: application/json" -H "User-Agent: commander-cli" --user "...:..." --data '{"user_id":"...","team_id":"...","command":"/nc","syncRequest":"true","text":" hello Nimbella"}' -X POST https://apigcp.nimbella.io/api/v1/web/nc/portal/cli-gateway

Support

We're always happy to help you with any issues you encounter. You may want to join our Slack community to engage with us for a more rapid response.

License

Apache-2.0. See LICENSE to learn more.