Basic Yetibot expressions

Help

The help command lets you explore the commands available and their usage. It has its own help doc:

!help help

!help

Response Types

Yetibot responses are either:

A single value

A collection of values

There are no other types in Yetibot, though the underlying Clojure data structures in responses may contain more diverse responses, such as when returning the result of an API call.

Here's an example of a collection:

!list 1 2 3

To view the raw underlying Clojure data structure type of a response in Yetibot, use raw. For example:

!list 1 2 3 | raw

Pipes

Pipes allow chaining together more complex expressions using the output of one command as the input of another command.

!echo 1 | echo 2 | echo 3

Notice how the output of each preceding command is appended to the end of the following command separated by a space. This is the default behavior, but you can also choose where to place arguments and control whitespace using %s:

!echo foo | echo %sbar

Subexpressions

Subexpressions let you build up more complex expressions by nesting one expression in another.

!echo `echo Hello` Yetibot

Backticks are convenient when you need a single level of nesting, but $() syntax lets you embed any level of nesting:

!echo $(echo $(echo Yetibot) is) `echo alive`

These examples are necessarily simplistic but when you start piecing together more complex commands that fetch data, the ability to arbitrarily nest expressions is quite useful.

Fun 🎉

Fun has always been an important part of Yetibot's existence. The full list of commands in the fun category can be listed via:

!category list fun

Below we document a few highlights.

Meme generation

Meme gen was one of Yetibot's first features 😂.

!meme yetibot: hello world!

!help meme

!catfact | meme

!chuck | meme chuck:

!jargon | meme yeah if you:

Giphy

!help giphy

!giphy reaction

!giphy whoa

!giphy random

!giphy trending

No

!help no

!no

Http

!http 404

!http 200

!http 401

!http 500

!http 420

Collection utilities

Since Yetibot can return a collection as a response, it needs basic operations to manipulate collections.

range

!help range

!range 10

!range 0 100 25

list

!help list

!list Yetibot is alive

xargs

xargs allows us to operate over a collection, evaluating an expression for each value, in parallel.

sort

sortnum

grep

tee

tee doesn't work in the GraphQL API yet, but you can try this out via chat:

!echo foo | tee | echo bar

reverse

!help reverse

!range 3 | reverse

droplast

!help droplast

!list first middle last | droplast

rest

!help rest

!range 10 | rest

Other collection commands

There are a few others not documented here such as raw, keys, vals`, and data (which is documented in its own section of this guide). To view them all we can look them up by category:

!category list collection

Aliases

Aliases are similar to alias in bash allowing us to give a name for a command. This is typically a heavily-used feature as teams build up aliases for fun or utility and become a manifestation of culture.

!help alias

Observers

An observer listens for patterns and automatically runs commands when triggered. They're super powerful but can be easily be abused.

!help observer

Run the above help docs. As you can see, observers support several different event types.

message

The default event type for observers is message. This allows Yetibot to react to a message by running a command. For example:

!obs sushi = react :sushi:

With this observer any time anyone mention sushi they get a 🍣 reaction. Note that we could have specified a regex pattern instead of the literal "sushi".

The above example also illustrates the templating functionality. Along with username and body, channel is available on all event types, and for react observer events, reaction and message-username are also available.

react

A react event fires when a user reacts to a message (Slack only).

!obs -c dev-testing -e react = giphy {{reaction}} {{body}}

This causes a giphy lookup using the reaction used (e.g. 100 or smile) and the body text of the message that was reacted to.

React events also have two other fields available: reaction and message-username where message-username is the username of the user that posted the original message (username is the username of the user that reacted).

We could go on and on (and on and on). render opens up a ton of possabilities for customizing command output and using Yetibot in unexpected and unanticipated ways!

Cron

Cron is, as you'd expect, a way to run a command on an interval given a cron expression.

!help cron

Eval

The eval command runs arbitrary Clojure against the Yetibot process itself, so it's by definition very insecure. Because of this, it's only allowed to be run by users that have been pre-configured to have access.

It can be a fun way of poking at otherwise-unavailable state inside Yetibot.

!help eval

Scrape

!help scrape

Channel settings

Arbitrary key/value pairs can be stored on a per-channel basis. This lets you do things like set channel local JIRA projects, Jenkins jobs, or other values that could for example be utilized by aliases.

!help channel

That

The that command retrieves the last non-command thing said, excluding Yetibot output, and that cmd retrieves the last command.

!help that

Example usage:

!that | meme insanity:

Karma

The karma command lets you increment or decrement another user's karma along with an optional note.

!help karma

View the leaderboard:

!karma

There are three ways to adjust a user's Karma.

The canonical !karma command invocation, using the traditional C increment (++) or decrement (–) operators, optionally followed by a note.

!karma @yetibot++ thanks Yetibot

!karma @yetibot-- you had one job

The Emoji versions to add (🌈) or subtract (⛈), optionally followed by a note.

🌈 @yetibot

⛈ @yetibot I told you to go before we got in the car!

Via Emoji reactions, which necessarily preclude the addition of notes.

At this time removing your Emoji reaction does not reverse the initial addition or subtraction of Karma.

In all cases, Yetibot will respond with the user's new score. Emoji reaction Karma is reported in a thread.

Now take a look at Yetibot's Karma:

!karma @yetibot

In addition to these commands, karma is also exposed via the GraphQL API!

JIRA

Yetibot's JIRA capabilities are fairly powerful. It can operate over a global list of projects or per-channel project settings. Operations include creating, updating, resolving, describing, deleting, assigning and commenting on issues.

The projects key is optional and specifies the global list of projects. This is mostly important for the observer that detects a JIRA task like PROJ-123 and auto outputs the details of the task, when found.

This ability is also configurable on a per-channel basis using channel settings:

!channel set jira-project YETIBOT

After setting that in a channel, Yetibot will know to expand all occurrences of strings that look like JIRA keys, such as YETIBOT-123.

Countdown

This alias uses JavaScript to determine the number of days till a specific date and outputs the day along with a string message. It could be further abstracted as a countdown alias that takes a date and a message, but we typically just re-define the alias as needed.

Alltemps

We use an alias to store the list of zip codes for all members of our distributed team, which we then feed to another alias which outputs a short single-line description of current weather for a location.