7. Commands and Bundles
As a chatops bot, commands are central to Gort. Let’s take a look at exactly what commands are, how they’re organized, and how they’re managed.
Let’s start with an example. Entering the following into Slack:
!gort:help
You should receive a response that looks something like this:
I know about these commands:
curl:curl
gort:bundle
gort:group
gort:help
gort:role
gort:user
gort:version
Typing !gort:help
executed the help
command from the gort
command bundle. From the response, you can see that the system currently
has two bundles installed (curl
, and gort
), each of which
contains one or more commands. The curl
bundle contains a single
command (also named curl
), and the gort
bundle contains several
commands, one of which is the help
command we just invoked.
Try calling gort:help COMMAND
to find out more about a specific
command:
!gort:help gort:user
This should provide a response like the following:
Part of the "gort" bundle.
Allows you to perform user administration.
Use "!gort:user --help" for more information about this command.
As indicated in the above output, many commands also support a dedicated
--help
argument (which is handled by the command executable, not by
Gort). For example, typing !gort:help --help
will return the
following:
Provides information about a command.
If no command is specified, this will list all commands installed in Gort.
Usage:
!gort:help [flags] [command]
Flags:
-h, --help Show this message and exit
7.1. Commands
If you think of Gort as a “shared command line”, then commands are like the executables in your terminal.
A given command may need some additional information that would not be shared on the “shared command line”, but will have to be setup by an administrator, such as an OAuth key. See Dynamic Command Configuration for more information on how to get this data for command execution.
7.2. Bundles
Bundles (or “command bundles”) are the packaging unit for collections of one or more commands.
Each references a single Docker container image that contains all the binaries and other dependencies for executing one or more commands. They also include some data about the commands, including a small amount of documentation and other metadata. See Writing a Command Bundle for more specifics.
Bundles can be installed into Gort by an administrator (or any user with
the manage_commands
permission) using the gort
command-line
utility. See Managing Bundles for more on bundle installation.
7.2.1. Bundle Permissions and Rules
Bundles also contain a set of permissions and authorization rules for their commands. When a bundle is installed, these permissions and accompanying rules are automatically created in the Gort system.
Since permissions are namespaced to the bundle they originate from, installing a bundle’s permissions will never conflict with any existing authorization system configurations you may have made. No users are automatically assigned any of these permissions.
7.2.2. Example: The gort
Bundle
The gort bundle is a unique bundle in that it is effectively built into the bot. All Gort instances will have this bundle installed automatically, which is how the core permissions and authorization rules of the system come to be installed.
7.3. Invoking Commands
To invoke a command, like gort:help
, you actually have a few
options.
First, you can use a “command prefix”, which defaults to !
.
!gort:help
You can also interact with the bot in 1-on-1 chat, in which case you may type commands directly; everything you type to the bot is considered a command.
gort:help
7.3.1. Shortcuts
Fully-qualifying all command names with their bundle name (i.e.,
gort:help
) can get tedious for frequently-used commands.
Fortunately, Gort allows a shortcut: if a command name happens to be
unique within a Gort installation (that is, no other bundles are
installed that have a command with the same name), you may type the bare
command. For example, gort:help
can be replaced with just help
,
so long as no other bundles have a help
command.
7.3.2. Triggers
You can also configure a command with “triggers” that will cause it to execute when a message matches a regular expression.
You can define one or more triggers for a command using the triggers field in the bundle yaml:
- ::
gort_bundle_version: 1 name: my_bundle …
- commands:
- my_command:
description: Example trigger configuration … triggers:
match: mytrigger
match: (?:[0-9]{1,3}.){3}[0-9]{1,3}
The example above will match all messages containing the text “mytrigger” as well as any message containing an IPv4 address.
7.4. Implementation Details
Every bundle has a Docker image that contains all of its commands.
By default, the command uses the image’s default entrypoint
to handle commands. However, if a command has an executable
defined,
then the given binary is used instead (like a Docker –entrypoint
parameter).
Any parameters you type into the command line are passed directly to the containerized binary, which can handle them just like a normal command-line execution. This allows you to implement your command using a CLI framework in any language you like.
Tip
See Commands As Containers for more details.