imubot/docs/index.md

A simple helpful bot.

---
title: Mubot
permalink: /docs/index.html
layout: docs
---

## Getting Started With Mubot

You will need [node.js and npm](https://docs.npmjs.com/getting-started/installing-node). Once those are installed, we can install the mubot generator:

    %  npm install -g yo generator-mubot

This will give us the `mubot` [yeoman](http://yeoman.io/) generator. Now we
can make a new directory, and generate a new instance of mubot in it. For example, if
we wanted to make a bot called mymubot:


    % mkdir mymubot
    % cd mymubot
    % yo mubot

At this point, you'll be asked a few questions about who is creating the bot,
and which [adapter](/docs/adapters.md) you'll be using. Adapters are mubot's
way of integrating with different chat providers.

If you are using git, the generated directory includes a .gitignore, so you can
initialize and add everything:

    % git init
    % git add .
    % git commit -m "Initial commit"

If you'd prefer to automate your mubot build without being interactively
prompted for its configuration, you can add the following options
to the `yo mubot` command to do so:

| Option                                      | Description
| ------------------------------------------- | -----------------------------------------------------
| `--owner="Bot Wrangler <bw@example.com>"`   | Bot owner, e.g. "Bot Wrangler <bw@example.com>"
| `--name="Mubot"`                            | Bot name, e.g. "Mubot"
| `--description="Delightfully aware robutt"` | Bot description, e.g. "Delightfully aware robutt"
| `--adapter=campfire`                        | Bot adapter, e.g. "campfire"
| `--defaults`                                | Declare all defaults are set and no prompting required

You now have your own functional mubot! There's a `bin/mubot`
command for convenience, to handle installing npm dependencies, loading scripts,
and then launching your mubot.

Mubot needs Redis to persist data, so before you can start mubot on your own computer, you should have Redis installed on your localhost. If just want to test Mubot without Redis, then you can remove `mubot-redis-brain` from `external-scripts.json`.

    % bin/mubot
    Mubot>

This starts mubot using the [shell adapter](/docs/adapters/shell.md), which
is mostly useful for development. Make note of  `Mubot>`; this is the name your mubot will
`respond` to with commands. For example, to list available commands:

    % bin/mubot
    mubot> mubot help
    mubot adapter - Reply with the adapter
    mubot animate me <query> - The same thing as `image me`, except adds a few parameters to try to return an animated GIF instead.
    mubot echo <text> - Reply back with <text>
    mubot help - Displays all of the help commands that mubot knows about.
    mubot help <query> - Displays all help commands that match <query>.
    mubot image me <query> - The Original. Queries Google Images for <query> and returns a random top result.
    mubot map me <query> - Returns a map view of the area returned by `query`.
    mubot mustache me <query> - Searches Google Images for the specified query and mustaches it.
    mubot mustache me <url> - Adds a mustache to the specified URL.
    mubot ping - Reply with pong
    mubot pronounce <phrase> in <language> - Provides pronunciation of <phrase> (<language> is optional)
    mubot pug bomb N - get N pugs
    mubot pug me - Receive a pug
    mubot the rules - Make sure mubot still knows the rules.
    mubot time - Reply with current time
    mubot translate me <phrase> - Searches for a translation for the <phrase> and then prints that bad boy out.
    mubot translate me from <source> into <target> <phrase> - Translates <phrase> from <source> into <target>. Both <source> and <target> are optional
    mubot youtube me <query> - Searches YouTube for the query and returns the video embed link.
    ship it - Display a motivation squirrel

You almost definitely will want to change your mubot's name to add character. bin/mubot takes a `--name`:

    % bin/mubot --name mymubot
    mymubot>

Your mubot will now respond as `mymubot`. This is
case-insensitive, and can be prefixed with `@` or suffixed with `:`. These are equivalent:

    MYMUBOT help
    mymubot help
    @mymubot help
    mymubot: help

## Scripts

Mubot's power comes through scripts. There are hundreds of scripts written and maintained by the community. Find them by searching the [NPM registry](https://www.npmjs.com/browse/keyword/mubot-scripts) for `mubot-scripts <your-search-term>`. For example:

```
$ npm search mubot-scripts github
NAME                  DESCRIPTION
mubot-deployer        Giving Mubot the ability to deploy GitHub repos to PaaS providers mubot mubot-scripts mubot-gith
mubot-gh-release-pr   A mubot script to create GitHub's PR for release
mubot-github          Giving Mubot the ability to be a vital member of your github organization
…
```

To use a script from an NPM package:

1. Run `npm install --save <package-name>` to add the package as a dependency and install it.
2. Add the package to `external-scripts.json`.
3. Run `npm home <package-name>` to open a browser window for the homepage of the script, where you can find more information about configuring and installing the script.

You can also put your own scripts under the `scripts/` directory. All scripts placed there are automatically loaded and ready to use with your mubot. Read more about customizing mubot by [writing your own scripts](/docs/scripting.md).

## Adapters

Mubot uses the adapter pattern to support multiple chat-backends. Here is a [list of available adapters](/docs/adapters.md), along with details on how to configure them.

## Deploying

You can deploy mubot to Heroku, which is the officially supported method.
Additionally you are able to deploy mubot to a UNIX-like system or Windows.
Please note the support for deploying to Windows isn't officially supported.

* [Deploying Mubot onto Heroku](/docs/deploying/heroku.md)
* [Deploying Mubot onto UNIX](/docs/deploying/unix.md)
* [Deploying Mubot onto Windows](/docs/deploying/windows.md)

## Patterns

Using custom scripts, you can quickly customize Mubot to be the most life embettering bot he or she can be. Read [docs/patterns.md](/docs/patterns.md) for some nifty tricks that may come in handy as you teach your mubot new skills.