Developer Guide
copied
Slack Apps
copied
Slack allows the use of custom Slack apps, which are accessed in Slack by means of Slash Commands. When a user types a specific slash command like /times
, it sends a message to a public URL. The request includes the command and any additional text following the command. Slack calls the public URL a Request URL. Custom Slack apps and slash commands are created using Slack's web interface at api.slack.com and linked to your custom code by means of the Request URL.
Slack apps with Nimbella Commander
copied
Commander provides a full development and runtime environment for developing custom Slack apps. There are a number of advantages to using Commander to develop, host, and maintain your custom apps.
You don’t need your own server
Commander lets you host and run Slack apps in the Nimbella Cloud, so you don’t have to deploy your own server. After you create a listing for your custom app on the Slack API apps page, you create one slash command and point the slash command’s Request URL to a Commander URL. Your app’s custom code lives in the Nimbella cloud, and Nimbella servers respond to slash commands developed for your app.
The slash command you create for your custom app at the Slack API site serves as a command prefix for your app’s commands. When users run commands for the app, they always begin with this prefix. For example, if you have a custom app called DevOps with a command prefix of /devops
, then your app responds to any slash commands that have the form /devops <command>
.
Selective listening
Most custom Slack apps function as bots, listening to all messages in a public channel and responding to direct requests. The apps you create with Commander don't read messages in channels. They only respond to slash commands with the appropriate command prefix. This means you don't have to worry about your custom Slack app reading messages in your public or private channels.
Create custom commands and administer your app right in Slack
After you install the Commander app in Slack, you can create custom slash commands and administer your custom app from the Slack interface. See the tutorial in the Quickstart Guide for an example of creating a custom slash command in the Slack UI.
Easy to code
Commands are written in JavaScript, and premium versions of Commander allow other options such as the Node.js runtime. This means custom apps can be developed by app developers or even DevOps staff who know shell scripting.
Advanced features
- Administrators assign user roles to control who can administer your custom app, who can write code for the commands, and who can run the slash commands.
- You can set up recurring tasks and triggers that run commands without user input.
- You can create encrypted parameter values, called secrets, which keep sensitive information from being viewed by users or being stored in Slack’s history.
- You can import and export command sets to either use someone else’s code or share your own.
Security
There's nothing you need to do to secure your app. The signatures of incoming requests from Slack users issuing Slack commands are verified to ensure they are coming from Slack. See Security.
Ready to get started?
copied
Check out the Commander Overview and then use the Quickstart to get started. Then follow this Developer Guide to understand where to go from there. Once you’re proficient, you’ll be able to look up commands in the Commander Reference Guide if you need a quick reminder.
About commands
copied
The Nimbella Commander app for Slack lets you control nearly all of the administrative functions for your custom app directly in the Slack interface by running slash commands with the command prefix /nc
. The entire set of Commander commands is listed in the Reference Guide. This Developer Guide also contains many examples of these commands, grouped by administrative function.
The current app
copied
Commander /nc
slash commands rely on the concept of a current app. If you are just creating commands that run with /nc
itself, you only have one app you are working with, the “nc” app. So, if you are just developing commands that run with the /nc
prefix, your current app will always be “nc”.
If you create a custom Slack app and connect that custom Slack app to Commander with the app_add command, that app will become your “current app”. If you have multiple apps in your workspace, you can use the app_current command to verify which app is being treated as the current app or make another app the current one.
Show the current app:

/nc app_current

Your current app is devops
Switch to the accounting app:

/nc app_current accounting
Command Parameters
copied
Commands support a variety of parameter definitions and Commander automatically parses parameters so they can be accessed easily in your source code.
When you create a command, you specify the parameters the command takes by enclosing parameter names in angle brackets. For example, the following command_create command creates a command for your custom app that will take two parameters:

/nc command_create add_host <hostname> <ip_addr>
In the code for the command, you can access the command's parameters by name using params:
if (params.hostname == 'a.nimbella.com') {
But also, the default generated command source code creates local variables as a convenience:
const {
Hostname,
Ip_addr
} = params;
This means you can access the parameters by name in a function without params:
if (hostname == 'a.nimbella.com') {
When a user runs this command in Slack, they add parameter values as in the following example (assuming the command prefix for the custom app is /devops
):

/devops add_host a.com 100.200.3.4
If you’re working on a command and discover you want to change the command's parameters, you can change them with the command_params command. For example, if you wanted to add a TTL parameter to the add_host command you created above:

/nc command_params add_host <hostname> <ip_addr> <ttl>
Note: If you use /nc command_params to create new parameters, the command source code is not regenerated, so to access those parameters directly by name without using params
, you'll need to add them to the list of local variables in the code first.
Parameter values with white space
When a command is run in your custom app, parameter values that include white space should be enclosed in a pair of either double or single quotes. For example, if you have a print
command with a <msg>
parameter, the value could be:

/devops print "This parameter has multiple words"
This command passes the value This parameter has multiple words
to the command source. If you want to pass a parameter value that includes the double quotes, use single quotes to enclose the string, such as:

/devops print ‘“Life is what happens when you're busy making other plans.” - John Lennon’
Note: On Apple computers (and potentially others), double quotes appear entered as either Unicode left or right double quotes. If the string starts with a Unicode left quote, a Unicode right quote will be expected to end it.
Optional command parameter
A list of parameters can end with one optional parameter in square brackets, such as the [<ttl>]
parameter in this example:

/nc command_create add_host <hostname> <ip_addr> [<ttl>]
This command can be run with either the first two parameters or all three, so either of these commands is valid:

/devops add_host a.nimbella.com 1.2.3.4

/devops add_host a.nimbella.com 1.2.3.4 300
Parameter options
The parameter definition for a command can also include options. Options are preceded with a hyphen (-). Options can be either be flags or named options. Here's an example that contains a flag option -detail
and a named option -ttl
with value ttl_value
:

/nc command_create add_host <hostname> <ip_addr> [-detail] [-ttl <ttl_value>]
In the source code for the command, you can check to see if a flag option is present either by using the params variable:
if (params.detail) {
or by its name alone, because the default generated code creates a local variable with the name of the option:
if (detail) {
Similarly, you can check if a named option exists by its name alone and check its value using the name of the value:
if (ttl && ttl_value == 30) {
The add_host
command created above with the -detail
and -ttl
options can be run in any of the following ways:

/devops add_host a.com 1.2.3.4

/devops add_host a.com 1.2.3.4 -detail

/devops add_host a.com 1.2.3.4 -ttl 90 -detail
Note:
- Options may not be used when an optional command parameter is present.
- When options are specified, they must be specified at the end of the parameter definition.
Variable number of arguments
Command parameter definitions support varargs
, a variable number of arguments. A parameter definition for a command with varargs
ends with the ellipsis notation (…). The following example specifies that the add_host
command can take any number of parameters:

/nc command_create add_host ...
When varargs
is used, you must code the command parameters to be parsed. In the command source code, the text of the full command, including the command prefix and all parameters, is available in commandText
:
let parts = commandText.split(" ");
let cmdPrefix = parts[0];
let cmd = parts[1];
Note: If you use varargs
, your parameter definition cannot include any optional command parameters or parameter options.
Slack Encodings
Slack automatically encodes certain input values. For example, if you type this command into Slack:
/nc route53_add www.example.com 1.2.3.4
Slack will see the www.example.com
parameter and since it looks like a hostname, it automatically encodes www.example.com
as a clickable link in the Slack interface.
Additionally, it encodes the value when sent as a parameter to the function. If a user typed the command above, the route53_add function would see this value as the first parameter:
https://www.example.com|www.example.com
instead of just www.example.com
.
Slack also isn't entirely consistent when encoding values. For example, if you type a full URI such as https://www.example.com
in Slack, it will encode it as just <https://www.example.com>
which is the parameter the function receives.
A convenient way to extract the URI from an encoded parameter is to match the parameter string against the following regex: ^<?([^|>]*)[|\w]*>?$
. This will tolerate the brackets <>
that wrap the URI, and will ignore all text after |
if it's present. When the string matches, the first regex group contains the decoded URI.
Slack also automatically decodes values in the above format. For example, if you output the value in the brackets above to print in Slack,
Slack will just display www.example.com
and it will be a clickable link that will direct to https://www.example.com
.
Create/manage custom apps
copied
Now we’ll create a custom Slack app with its own command prefix, which involves the following tasks:
- Create a Slack app for the DevOps team. The app could eventually contain a number of slash commands to accomplish tasks that DevOps normally performs.
- Create a slash command called /devops. We’ll create a slash command in the DevOps app that will serve as a command prefix when you run commands in Slack.
- Install the app into Slack.
- Connect the app to Commander.
- Create a print command that can be used for various notifications.
List all apps connected to Commander.
Create a Slack App for DevOps
copied
Make sure you’re logged into your Slack workspace before starting.
- Go to https://api.slack.com/apps.
Click Create New App.
In the Create a Slack App panel, enter the following information. a. For AppName, enter DevOps. b. For Development Slack Workspace, choose your workspace.
Click Create App to close the panel and create the app. This returns you to the Basic Information page.
Create a /devops Slash Command Prefix
copied
Assuming you’ll have a number of apps with various slash commands, it can get difficult to keep them all straight, and Slack doesn’t have a formal namespace built into their commands. We’ll create a slash command in the DevOps app that will serve as the command prefix for all the commands that we create for that app.
On the Basic Information page, click Slash Commands.
Click Create New Command.
On the Create New Command page, enter the following information: a. For Command, enter
/devops
. b. For Request URL, enter https://nimbella.com. We’ll go back and change this URL after we get the correct one for this app. c. For Short Description, enter DevOps Operations. d. Select the checkbox for Escape channels, users, and links sent to your app.In the Preview section, check your entries. As shown in this screenshot, the preview shows the information you entered and the slash command as it will be typed into Slack.
- Click Save.
This returns you to the Slash Commands page.
Install the app
copied
- In the left sidebar menu, in the Settings section click Install App.
Click Install App to Workspace.
Accept the default permissions and click Allow.
If the app is installed successfully, you’ll see a screen with the OAuth access token.
Connect the App to Commander
copied
We’ll use the Commander app’s /nc
command to add our DevOps app to Commander.
First, let’s talk about the syntax of the Nimbella Commander app_add
command that’s used to add an app to Commander:

/nc app_add <app-name> <command-prefix>
The parameters in this command are:
<app-name>
This will be the lower-case version of our app name, in this case devops<command-prefix>
The command prefix that we created in the last task. In this case, /devops.
To connect the DevOps app to Commander:
In Slack, run the following command:
User 7:41 PM
/nc app_add devops /devopsYou should see a Commander response that looks something like this:
Commander App 7:41 PMThe devops app has been added. Please attach this Request URL to the /devops command in Slack: https://apigcp.nimbella.io/api/v1/web/just-an-example-1234-5678/app_000/router
Copy the URL that appears in the response.
- Go to https://api.slack.com/apps.
In the App Name list, select the DevOps app.
Click Add features and functionality.
In the Features section in the left sidebar, click Slash Commands.
Click the Edit icon to the right of the
/devops
command.Replace the Request URL with the one that you copied.
Click Save.
The/devops
slash command (which will serve as the command prefix) is now connected to Commander. From now on, you’ll use Commander’s /nc
slash commands to create commands for the DevOps app, as we’ll do in the next section.
Create a Print Command
copied
Now we’re ready to create our first command in our DevOps app. We’ll use Commander right in Slack to create a print
command, with a parameter that we can then use for various types of notifications in our DevOps app. We’ll use this command in our GitHub example in the Triggers section to notify us that something has changed in our GitHub repository.
In Slack, enter the following slash command exactly as it appears here, including the angle brackets:
User 7:41 PM
/nc command_create print <msg>You’ll see a response similar to the following:
Commander App 7:41 PMCreated command print <msg>, edit the code
Click the link to edit the Commander code for the command.
- Find this line in the source code:Change the line to this:
"This is a default response for a newly created command with text: " + commandText
text: msg
- Click Save.
In Slack, test the command by entering the command prefix (
devops
), followed by the command (print
), followed by a text string for themsg
parameterUser 7:41 PM
/devops print Howdy!If your
print
message has more than one word, surround it with single or double quotes or else you’ll get a response that a parameter was not found. You should see the Slack response shown in this screenshot, coming from your custom app and displaying the print message.
Note that we created the command with an/nc
slash command, but we ran the command in in our DevOps app with our /devops
command prefix.
List all apps connected to Commander
copied
Use the app_list command.
List all the apps in your Slack workspace that are connected to Commander:
User 7:41 PM
/nc app_list
Create/manage commands
copied
Create a command for your custom app
Use command_create to create custom slash commands for the current app. Put parameters to be created in angle brackets.
Create an
add_host
command with parameters for hostname and IP address:User 7:41 PM
/nc command_create add_host <hostname> <ip_addr>Outputs a link to the Nimbella Cloud command source code, which you edit.
If you lose this link or want to go back to it later, use the command_code command.
See the tutorial in the Quickstart Guide for a detailed example of creating the command in Slack and following the link to add code.
Retrieve the source code link for a command
Use command_code to retrieve the link to the source code for a command you’ve already created. A link is generated that will work for 24 hours.
- Retrieve the code link for the
add_host
command:User 7:41 PM
/nc command_code add_host
List all commands in the current app
Use command_list.
- List all of the commands in the current app:User 7:41 PM
/nc command_list
Info about a command
Use command_info to get the following information about an individual command:
- When it was created
- Who created it
- When the source was last modified
- Who modified the source
This information appears in the command output.
- Get information about the
add_host
command:User 7:41 PM
/nc command_info add_host
View or set a command’s short description
Commands have a short description that describes what they are or what they do. Use command_desc to view or create the short description. If you’re adding a description that has white space, enclose the value in single or double quotes.
- View the short description of the
add_host
command:User 7:41 PM
/nc command_desc add_host - Set the short description of the
add_host
command:User 7:41 PM
/nc command_desc add_host "Adds a hostname"
Call a webhook for a command
Commander automatically executes the source code for a command when it is run in Slack. If you don't want the command to automatically run its source code, you can set it to call a webhook instead with command_webhook. When a webhook is set up for a command, the associated webhook URL will be contacted and its result returned to Slack instead of running the command's source code.
Tip: A command webhook can be useful when developing code. Use a webhook relay to proxy a command to your local development machine to develop and debug the command source code locally. After setting up a webhook relay to your local machine, you can run a Node server locally that will execute the command when it is run in Slack.
- Set up a webhook with the URL of the webhook relay to contact when the
add_host
command is run:
You can revert to executing the source code for the command by first clearing the webhook, then using retrieve the link to the code editor to save the command code.
- Turn off the
add_host
command webhook:User 7:41 PM
/nc command_webhook add_host clear - Retrieve the link to the code editor to save the
add_host
source code and return to running the command normally:User 7:41 PM
/nc command_code add_host
If you need to, you can use command_log to get the log history of the command to see who ran the command at what times and also the time it took the command to execute. See the Logs section for more information.
- Get the log history of the add_host command:User 7:41 PM
/nc command_log add_host
Delete a command
Use command_delete plus the command name.
- Delete the
add_host
command:User 7:41 PM
/nc command_delete add_host
Add npm packages for a command
copied
If your command source code is written in JavaScript and your command requires additional npm (Node Package Manager) packages to run, you can install them in your JavaScript source code with this function, which accepts an array of npm packages to install:
async function install(pkgs) {
pkgs = pkgs.join(' ');
return new Promise((resolve, reject) => {
const { exec } = require('child_process');
exec(`npm install ${pkgs}`, (err, stdout, stderr) => {
if (err) reject(err);
else resolve();
});
});
}
The following example shows the install()
function being used to install two npm packages:
let packages = [ 'read-installed', 'chalk' ];
await install(packages);
After installing the npm packages, they can be used as they normally would with require()
. This example shows the read-installed package being used:
var readInstalled = require('read-installed');
readInstalled("/", { depth: 0, dev: true }, function(err, map) { … })
Note: The installation of npm packages takes a little time, so commands that install packages will start up slower than those that do not.
To speed up subsequent runs of a command function that installs packages, the package references returned from the require()
statement can be moved into global variables in the command source code and the packages are only loaded if those values are undefined. This method will cause the packages to be installed the first time the command is executed. Note that they do not need to be installed if the same execution environment is used again by the underling serverless platform. When serverless function environments are reused in a serverless platform, the globals can maintain their previous values.
For example, if the readInstalled
variable above was global, the code could look like this:
var readInstalled;
function _command(...) {
if (!readInstalled) {
let packages = [ 'read-installed', 'chalk' ];
await install(packages);
readInstalled = require('read-installed');
}
}
The first time the code is executed, readInstalled
is undefined and the packages loaded. If the environment is reused later by the underlying serverless platform, the readInstalled
value can be used without installing the packages.
Create/manage user roles/groups
copied
About user roles
copied
For examples of assigning these user roles, see Commands to manage users and user groups.
Admin
In Commander, every custom Slack app starts with one administrative user: the Slack user who initially adds the custom app to Commander. It’s up to that admin to assign other Slack users as admins for that app. Admins in turn can assign users as coders for specific commands in the app and as runners of specific commands in the app.
Admins can also create user groups to make it easier to set coder and runner roles for multiple users. See the command examples below.
Admins have no restrictions on what they can do when it comes to an app. Only admin users can create commands, assign roles to other users, and perform other administrative tasks. Admins can do anything that coders and runners can do.
Coder
The coder role is associated with specific commands. A Slack user with a coder role for a command is allowed to edit the source code for the command and also run the command. App admins manage the list of coders for commands. Coders are automatically runners for the commands they can edit.
Runner
The runner role is associated with specific commands ii the custom app. A Slack user with a runner role for a command is allowed to run that command. They cannot run commands in the Commander app.
About user groups
copied
Instead of assigning Coder and Runner roles to individual users, admins can combine users into user groups to make it easier to set coder and runner roles for multiple users. The entire user group can then be added or removed as coders or runners for a command.
Commands to manage users and user groups
copied
Manage admin users
Use the app_admins command to list, add, or remove Slack users as admins for the current app. A plus (+) in front of a user name adds the user to the list and a minus (-) removes a user from the list.
Note: There must be a space between the plus (+) and minus (-) signs and the user to be added or removed as admins for the current app.
- List the users who are admins for the current app:User 7:41 PM
/nc app_adminsCommander App 7:41 PMdevops admins: Sam, Jill
- Add Bill and Mary and remove Larry as admins for the current app:User 7:41 PM
/nc app_admins + @Bill + @Mary - @Larry
Manage coder users
Use command_coders to list, add, or remove users as coders for particular commands.
- View the current list of coders for the add_host command:User 7:41 PM
/nc command_coders add_host - Add Jim and Bob and remove John as coders for the print command:User 7:41 PM
/nc command_coders print + @Jim + @Bob - @John
Manage users who run commands
Use command_runners to list, add, or remove users as runners for particular custom commands.
- Add Joe and Sue and remove John as runners for the print command:User 7:41 PM
/nc command_runners print + @Joe + @Sue - @John
Allow anyone to run a custom command
There is a special user group that always exists called anyone
, which includes every Slack user. If you want to allow a command to be run by anyone
, you can add the anyone group to the list of command runners:
- Let anyone run the print command: User 7:41 PM
/nc command_runners print + anyone
Create user groups
Use group_create to create a user group.
- Create a user group called devgroup1:User 7:41 PM
/nc group_create devgroup1
List, add, or remove members of a user group
Use the group_members command.
- Add Sue to devgroup1:User 7:41 PM
/nc group_members devgroup1 + @Sue - Add Jim, Bob, and John and remove Sue from devgroup1:User 7:41 PM
/nc group_members devgroup1 + @Jim + @Bob + John - @Sue - List the members of devgroup1:User 7:41 PM
/nc group_members devgroup1Commander App 7:41 PMdevgroup1 members: Jim, Bob, John
List all user groups
Use the group_list command.
- List all user groups for the current app.User 7:41 PM
/nc group_listCommander App 7:41 PMdevgroup1
Delete a user group
Use the group_delete command to delete a user group. Only the named group of users is deleted, the command does not affect the Slack users themselves in any way.
- Delete the user group devgroup1:User 7:41 PM
/nc group_delete devgroup1
Add a user group to a command
We gave examples of using command_coders and command_runners to add users as coders and runners respectively. Here are two examples of adding a user group instead.
Add the user group devgroup1 as coders for the print command:
User 7:41 PM
/nc command_coders print + devgroup1Add the user group bookkeeping as runners for the bills command:
User 7:41 PM
/nc command_runners bills + bookkeeping
Secrets
copied
Users in Commander can create secrets, which are key-value pairs where the value is encrypted. The key is an arbitrary name, and the value represents an input parameter that should not be visible, such as an API key or password. Secret values appear as command function input parameters with the value automatically decrypted as it is passed to the command function’s source code.
When a user creates and adds secrets, the secret key/values are passed to every command function in the app that specific user runs. Administrator users of a Commander app can create global secrets. Global secrets are passed as input parameters to every command run by every user.
Secrets are specific to a Commander app. One Commander app can't see another Commander app's secrets.
Commander has a Secret Creator web user interface (UI) where users create key-value pairs. After creating a secret, the user should copy the “secret_add” command for each secret and paste it into Slack. That way, unencrypted secret values are stored outside of your app's source code and never appear in plain text in Slack.
Each Slack app contains a unique encryption key to encrypt the values for all key-value pairs. Secrets encrypted for one app can't be decrypted by any other app. The encrypted values are stored in a Commander app using AES-256-bit symmetric encryption.
Here’s an overview of how secrets are created, with detailed procedures below:
- Use the
secret_create
command in Slack, which outputs a link to the Secret Creator. - Create the key-value name pairs in the Secret Creator and click a button to encrypt the values.
The Secret Creator outputs a
secret_add
command for each key-value pair you’ve created. - Copy and paste the
secret_add
commands into Slack to add them to your app.
Note: By default, the global checkbox is checked for each secret key/value pair when an administor user runs the secret_create
command. Uncheck the box if you are an administrator who wants to create a secret that is specific to you.
Here are examples of procedures related to secrets.
Create secret key-value pairs and add them to your app:
Enter the following command into Slack:
User 7:41 PM
/nc secret_createCommander App 7:41 PMclick here to access the Secret Creator
In the Secret Creator UI, add a set of name-value pairs, then click Make Secrets. The Secret Creator outputs a list of secret_add commands, as in this example:
User 7:41 PM
/nc secret_add awsKey NFa_305fe79...c21e4285385f17_User 7:41 PM
/nc secret_add gwpKey NFa_5c67f7b...85e915084650f6_Copy and paste each secret_add command from the Secret Creator output into Slack to add the encrypted key-value pairs to your current app.
View an app’s secret key-value pairs
copied
Use the secret_list command.
List this user’s secret key-value pairs and all global secret key-value pairs:
User 7:41 PM
/nc secret_listThe output is a list of keys with their encrypted values. Only the beginning and end of the encrypted values are shown for each secret because the encrypted values can get rather long.
Delete a secret
copied
Use the secret_delete command in Slack with the name of the secret key.
Delete the secret key-value pair named
gc_key
:User 7:41 PM
/nc secret_delete gc_key
Access the decrypted value of a secret in your command code
copied
Once added to your app, decrypted secret values can be accessed in source code using the secrets
input parameter.
- Example code that accesses a secret value with the key
mySecretApiKey
:async function my_command(params, text, secrets = {}) { if (!secrets.mySecretApiKey) { return { text: "you need a mySecretApiKey secret to run this command" }; } .. connect to API using secrets.mySecretApiKey .. }
- Look in the command source code under the secrets input parameter. For example:
awsConnection = createAwsConnection(secrets.awsKey); gwpConnection = createGwpConnection(secrets.gwpKey); …
Logs
copied
Commander has three log commands to view logs for an app, command, or user respectively:
The log commands are straightforward and currently only have the functionality to display the logs. Here are examples of each being used:
Show the log for the current app:
User 7:41 PM
/nc app_logOutput example:
Commander App 7:41 PM343. user_log @Joe Ran by @Joe 10/18/2019, 12:19:13 AM (App: /devops)
Commander App 7:41 PM342. command_code print Ran by @Joe 10/17/2019, 11:26:08 PM (App: /devops)
Show the log for the
add_host
command:User 7:41 PM
/nc command_log printOutput example:
Commander App 7:41 PM8. print Ran by @Joe 10/17/2019, 6:49:34 PM Execution time 125ms with status 200 (App: /devops)
Commander App 7:41 PM7. print Ran by @Joe 10/17/2019, 1:30:53 PM Execution time 122ms with status 200 (App: /devops)
Show the log for user
@Sam
:User 7:41 PM
/nc user_log @SamOutput example:
Commander App 7:41 PM404. command_delete print Ran by @Sam 10/17/2019, 6:49:20 PM (App: /devops)
Commander App 7:41 PM403. command_list Ran by @Sam 10/17/2019, 6:48:20 PM (App: /devops)
Tip: Every log has a line number. To go back in history, log commands support a -from
option with a line number parameter, for example:

/nc app_log -from 90

/nc command_log add_host -from 210

/nc user_log @Rick -from 300
More advanced features, such as searching logs and allowing them to be exported will be supported in future releases.
Channels
copied
By default, Slack apps that use Commander can only output to Slack in response to a Slack command. Tasks, which run a command at an interval or rate, and triggers, which connect external webhooks to commands, aren’t run by users, so they require the ability to post to a Slack channel on their own. Commander includes channel commands that enable triggers and tasks to post in channels on their own.
Note: If you aren't using tasks or triggers, you don't need to add channels to your app
Create/add a channel
copied
In Commander, a channel is associated with an incoming webhook that can post into that channel. To allow your app to post in a channel, you must first create an incoming webhook for that channel in a custom Slack app, then add it to Commander using the channel_add command. You can use this command with a public, private or locked channel. When you add a channel, a message is posted into that channel to let you know the channel was added to Commander.
Here’s how to create a channel and add it to Commander. In this example, let’s add a channel called #devops-output
to the custom DevOps app that was created in the Quickstart Guide.
To create a channel in your custom Slack app:
- If you want to use a channel other than one that already exists in Slack, create it.
In this example, we created a
#devops-output
channel. - Go to https://api.slack.com/apps.
- Select the DevOps app.
- Click Add features and functionality.
- Click Incoming Webhooks.
- Enable Incoming Webhooks.
- Click Add New Webhook to Workspace.
- Select the channel you want the task to output to and click Allow.
- Click Copy for the webhook URL you just created.
- In Slack, run the following command, substituting the values for channel name and webhook URL:

/nc channel_add #devops-output <webhook URL>
Replace <webhook URL> by pasting in the webhook URL that you copied in the previous step.
Example:

/nc channel_add #devops-output https://hooks.slack.com/services/BAHCHA1928/BGHA018481/6jaKjsAHhADKJAd
Note: After you add the channel, you need to set the channel for your task or trigger. See the Tasks and Triggers sections for example commands.
List channels added to your app
copied
Use the channel_list command.
- To list all channels added to the current app:User 7:41 PM
/nc channel_list
Delete a channel
copied
Use the channel_delete command with the channel name as a parameter.
- Delete the
#devops-output
channel from Commander:User 7:41 PM
/nc channel_delete #devops-output
Note: This command does not delete the channel's incoming webhook from Slack. To delete the channel's incoming webhook, delete it from Slack using api.slack.com.
Tasks
copied
Tasks run commands at scheduled times or at a given rate.
There are several commands to create and manage tasks. After creating a task, you can set its schedule or interval with task_schedule or task_rate and then start the task running with task_start.
Create a task
copied
Use the task_create command with parameters for the task name, output channel, and the command to run.
Create a task called mytask
, output to the #general
channel, and run the print
command with the parameter “Hello World
”:

/nc task_create mytask #general print "Hello World"
View or set the task rate
copied
Use task_rate. The command includes the optional parameters <value>
and <unit>
to set the rate, where <value>
is a number and <unit>
is one of: minute, minutes, hour, hours, day or days
.
Notes: After you set the rate, use task_start
to start the task. If a task is running, it must be stopped with task_stop
before the rate can be changed.
- View the task rate for
mytask
:User 7:41 PM
/nc task_rate mytask - Set the task rate for mytask to 15 minutes:User 7:41 PM
/nc task_rate mytask 15 minutes - Set the task rate for
mytask
to one day:User 7:41 PM
/nc task_rate mytask 1 day
Start the task
copied
Use task_start. You can also restart a task with this command after using task_stop
.
Start
mytask
:User 7:41 PM
/nc task_start mytask
Stop the task
copied
Use task_stop. Stopping a task doesn't delete it or change it, it just stops the task from running. You can view or set the schedule or rate of a task with the task_rate and task_interval commands. A task must be stopped to change its schedule or rate.
Stop
mytask
:User 7:41 PM
/nc task_stop mytask
List all tasks
copied
Use task_list to output a list of all tasks in the current app and their states.
To list all tasks and their states:
User 7:41 PM
/nc task_list
Get info about a task
copied
Use task_info to show the following information about the task:
- Name
- Creator
- Schedule or rate
- Status (stopped or running).
- If the task was started or stopped, the time it started running or when it was stopped is shown.
This information appears in the command output.
Show the task information for
mytask
:User 7:41 PM
/nc task_info
View or set the channel for task
copied
Use task_channel to view or set the channel associated with a task.
View the channel used for
mytask
:User 7:41 PM
/nc task_channel mytask
If you’re setting or changing the task channel, be sure that the channel has been created in your Slack app and added to Commander.
Set or change the task output channel for
mytask
to#general
:User 7:41 PM
/nc task_channel mytask #general
Delete a task
copied
Use task_delete to delete a specific task.
Delete
mytask
:User 7:41 PM
/nc task_delete mytask
Triggers
copied
Triggers allow an external webhook to trigger execution of a command and output the results to a Slack channel. When a trigger is created, an incoming webhook URL is created for the trigger that you have set an external webhook to call when an event takes place.
Like tasks, triggers aren't run by users, so they need a way to output to a Slack channel that you’ve created and added to your app.
Example: Create a trigger for a GitHub webhook with trigger_create
copied
As an example, you might want to set up a webhook for Github push events where a Github push (a transfer of commits to a repository) causes a command to be run to notify users in a Slack channel that a push took place. Here’s the sequence of tasks to set this up, with detailed instructions following:
- Choose which Slack output channel you want to use (add a channel to Commander if you haven’t already) and which command to trigger. In this case, we’ll use the existing #general channel and the print command that was in the Quickstart Guide tutorial
- Create a trigger with an output channel and output message, using trigger_create. This command outputs an incoming URL in the Nimbella Cloud.
- Use this incoming URL to create an external webhook in GitHub that notifies the incoming URL each time there’s a push in the repository.
Github has documentation about their webhooks on developer.github.com, but here are basic instructions:
To set up a trigger for a GitHub webhook to print Slack notifications when there’s a repository push:
In Slack, create a trigger called GHpushTrigger that writes the output from the
print
command to the #general channel:User 7:41 PM
/nc trigger_create GHpushTrigger #general print “Hey there’s been a push in your GitHub repo!”Commander App 7:41 PMcreated trigger printTrigger with incoming URL https://agigcp.nimbella.com/AHC901230/nc/v1
Copy the incoming URL in the response.
- In GitHub, choose your repository.
- Click the Settings tab.
- Click Webhooks in the left sidebar.
- Click Add Webhook.
- In the Payload URL field, paste the incoming URL of the trigger you created.
- Select application/json as the Content type.
- Select Just the push event.
- Make sure the Active checkbox is selected and click Save webhook.
Now any Github push event in the GitHub repository will cause the print command to be run and the output sent to the #general channel.
Access GitHub event information
When Github sends an event using a webhook, it puts information about the event in an "X-Github-Event
" HTTP header. The params.__trigger
variable in your command has all the HTTP headers and parameters of the incoming request, so you can access the Github event information with params.__trigger.X-Github-Event
:
JSON.stringify(params.__trigger.X-Github-Event, null, 2)
Other commands for managing triggers
copied
Disable a trigger
Use trigger_disable. Disabling a trigger doesn't delete it or change it, it just stops the task from running the command.
- Disable the
GHpushTrigger
trigger:User 7:41 PM
/nc trigger_disable GHpushTrigger
Re-enable a trigger
The trigger_create
command automatically enables the trigger, but if you run the trigger_disable
command, you can re-enable the disabled trigger using trigger_enable.
- Re-enable
GHpushTrigger
:User 7:41 PM
/nc trigger_enable GHpushTrigger
Info about a trigger
The trigger_info command shows information about a trigger.
List all triggers
Use the trigger_list command to get a list of all the triggers in the current app.
- List all triggers in the current app:User 7:41 PM
/nc trigger_list
View/set the channel associated with a trigger:
Use trigger_channel.
- View the channel associated with
GHpushTrigger
:User 7:41 PM
/nc trigger_channel GHpushTrigger - Set the channel associated with
GHpushTrigger
:User 7:41 PM
/nc trigger_channel GHpushTrigger #general
Delete a trigger
Use the trigger_delete command.
Note: If you delete a trigger, you should first delete the external webhook that is calling it so you don't end up with a webhook that continues to call an endpoint that doesn't exist.
- Delete the
GHpushTrigger
trigger:User 7:41 PM
/nc trigger_delete GHpushTrigger
Command Sets
copied
Command sets can be used to install, manage or publish a set of commands. A command set contains the definition of each command in the set, including the command's name, parameters, and a description. A command set also includes the source code for each command in the set.
Command sets are defined by a YAML file in OpenCSI Specification format. The YAML file includes links to the source code for each command. Put the YAML file in a web-accessible location, along with the source code for each command. Installing the command set using the csm_install command brings in the commands and their source, so the source can be customized at the new location. The process is similar to installing npm (Node Package Manager) packages.
You can install publicly available command sets in several different ways, as shown in the following examples.
Example 1: Install the Nimbella billing command set
copied
Nimbella maintains links to commonly used command sets that can be installed using single-word names. For example, there is a billing
command set that contains billing commands for common cloud services, such as Amazon Web Services. See the Example command sets section for a list of the example command sets available.
Note: Many of the commands in the billing
command set require API keys to allow the command source to obtain billing information from the various cloud providers. For example, to use the awsbill
command, you must create secrets for awsCostExplorerAccessKeyId
, awsCostExplorerSecretAccessKeyId
, and awsCostExplorerRegion
. See the Secrets section for how to access information and API keys that need to be added to run the commands that require them. The various commands will output what API keys are required when they are run and what secrets are missing that they need.
Install a command set
Install the
billing
command set in the current app, along with the source for the commands:User 7:41 PM
/nc csm_install billing
Output: List of commands installed.
Use csm_commands at any time to see the list of commands that were installed in this command set:
List the commands installed with the
billing
command set:User 7:41 PM
/nc csm_commands billing
Customize and edit the source code of any of the installed commands using command_code to get a link to edit the command's source code.
Retrieve a link to the
awsbill
command’s source code:User 7:41 PM
/nc command_code awsbill
Example 2: Install a command set from a GitHub repository
copied
The Github repository has a commands.yaml file in its root directory that contains the OpenCSI YAML definition of the command set. You can publish your own command set for others to use by putting a commands.yaml file for the command set into a GitHub repository. The commands.yaml file contains the definition of each command along with links to the source code for each command.
Anyone Installing this command set from Github would use the following command:

/nc csm_install github:<name>/<project>
Example 3: Install a command set from a URL
copied
A third way to install a command set from an external location is by specifying the full URL of the command set YAML definition.
Install a command set YAML from the URL https://a.b.com/commands.yaml:
Commands to manage command sets
copied
Update an externally loaded command set
If an externally loaded command set is updated, you can update the source for all the commands from the source location with csm_update.
Update the
billing
command set:User 7:41 PM
/nc csm_update billing
Notes:
- Any changes you made to the source code of the commands in the set are overwritten by running
csm_update
. - Github runs a caching service in front of the Github web site, so if a command set is updated on Github an update may not immediately reflect the changes to the command set.
List all the command sets and commands in each command set
The csm_list command outputs all the command sets in the current app and also all the commands in each command set. There are no parameters.
List all command sets and all commands in each set in the current app:
User 7:41 PM
/nc csm_listCommander App 7:41 PMbilling: awsbill, datadogbill
The output shows there is one command set (
billing
) with two commands:awsbill
anddatadogbill
List the commands in a specified command set
Use csm_commands to see the list of commands included in one command set:
List the commands installed with the
billing
command set:User 7:41 PM
/nc csm_commands billing
Show information about a command set
The csm_info command provides the following information for a specified command set that was loaded with csm_install
:
- Name of the command set
- URL location
- Version number
- Description of the command set
Note: This command doesn’t work with command sets created with csm_create
.
Uninstall a command set
Use csm_uninstall to uninstall a command set.
Note: This command also deletes all the source code for the commands in the set, even if the source has been modified. To prevent this, delete the command set instead.
Uninstall the
billing
command set:User 7:41 PM
/nc csm_uninstall billing
Delete a command set
Use csm_delete to delete a named command set. Only the command set is deleted – the commands in the set are unaffected by this command. If you want to delete the commands as well, use the csm_uninstall command instead.
Delete the billing command set from the current app:
User 7:41 PM
/nc csm_delete myset
Create and manage a custom command set
copied
First, create a command set, then add and remove commands in a second step.
Create a command set
Use the csm_create command to create an internal command set.
Create a command set called
myset
:User 7:41 PM
/nc csm_create myset
Add and remove commands
Use csm_commands to add and remove commands from a command set. Use plus signs to add and minus signs to remove. Leave a space after the plus or minus sign.
Add the commands
mycommand1
andmycommand2
to themyset
command set:User 7:41 PM
/nc csm_commands myset + mycommand1 + mycommand2
The csm_commands
command without the optional parameters lists the commands included in this command set.
Export an OpenCSI definition of your internal command set
The csm_export command outputs an OpenCSI definition for a command set. You can copy that definition to an external location, such as into a commands.yaml file in a Github repository, then put in references to the source code for the commands.
Output an OpenCSI definition for the
myset
command set:User 7:41 PM
/nc csm_export myset
Example command sets
copied
A large number of pre-built command sets are available. All command sets include source code.
The list of command sets that can be installed with single word names is available here:
https://github.com/nimbella/command-sets
See Example 1 for how to install and view the commands in the billing
command set.
Security
copied
You’ll notice when you install the Commander app in Slack, it doesn’t ask for permissions to read messages. Commander does not read messages in any channel, it is output only and only responds to slash commands connected to commander. All connections from Slack to Commander must be explicitly made by a Slack workspace administrator.
When you install Commander, it doesn’t read any of your messages. It can’t create custom Slack slash commands on its own. It also doesn’t have access to read from any of the channels but it can post in a channel.
For example, if you want a Commander task to post a message in a Slack channel, you must create an incoming webhook URL for the channel and give that webhook URL to Commander with the channel_add command. That isn't necessary for slash commands that users type into a channel. When your custom Slack app is in your workspace and you type custom commands, it has permission to post in the channel the command is run from.
User and team identities are automatically managed by Slack. When Slack slash commands are executed, Commander ensures Slack is the caller using a shared secret key. HTTPS is used for all communications. Internally, Commander uses the Nimbella Cloud. In the Nimbella Cloud, each command function executes in an isolated container, with its environment separated from other containers. Apps in Commander are each separated by namespaces with their own authorization keys.
Manage Accounts
copied
When you add an app to Commander, an account is automatically created for you and tied to your Slack workspace. All apps added to the same Slack workspace share the same account.
Accounts have plan information (paid/unpaid) and various limits associated with them.
- To view the account information associated with your Slack workspace, including the plan and limits, use account_info.
- If you want to increase your account limits and upgrade your plan, use the account_upgrade command to start the upgrade process for your Slack workspace. This command outputs a web link that will take you to a web page showing your upgrade options and various plan costs.
Upgrading
copied
The free version of Commander has limitations in terms of commands, tasks, and triggers and only allows commands to be written in JavaScript. Upgrades are available on a Slack workspace (team) basis to give all apps in the workspace higher limits and enable more features. Upgrades include the ability to allow direct development using the Nimbella workbench.
See the pricing page for more information.