1 | ---
|
2 | permalink: /docs/
|
3 | ---
|
4 |
|
5 | ## Getting Started With Hubot
|
6 |
|
7 | You will need [node.js and npm](https://docs.npmjs.com/getting-started/installing-node). Once those are installed, we can install the hubot generator:
|
8 |
|
9 | % npm install -g yo generator-hubot
|
10 |
|
11 | This will give us the `hubot` [yeoman](http://yeoman.io/) generator. Now we
|
12 | can make a new directory, and generate a new instance of hubot in it. For example, if
|
13 | we wanted to make a bot called myhubot:
|
14 |
|
15 |
|
16 | % mkdir myhubot
|
17 | % cd myhubot
|
18 | % yo hubot
|
19 |
|
20 | At this point, you'll be asked a few questions about who is creating the bot,
|
21 | and which [adapter](adapters.md) you'll be using. Adapters are hubot's
|
22 | way of integrating with different chat providers.
|
23 |
|
24 | If you are using git, the generated directory includes a .gitignore, so you can
|
25 | initialize and add everything:
|
26 |
|
27 | % git init
|
28 | % git add .
|
29 | % git commit -m "Initial commit"
|
30 |
|
31 | If you'd prefer to automate your hubot build without being interactively
|
32 | prompted for its configuration, you can add the following options
|
33 | to the `yo hubot` command to do so:
|
34 |
|
35 | | Option | Description |
|
36 | |:--------------------------------------------|:-------------------------------------------------------|
|
37 | | `--owner="Bot Wrangler <bw@example.com>"` | Bot owner, e.g. "Bot Wrangler <bw@example.com>" |
|
38 | | `--name="Hubot"` | Bot name, e.g. "Hubot" |
|
39 | | `--description="Delightfully aware robutt"` | Bot description, e.g. "Delightfully aware robutt" |
|
40 | | `--adapter=campfire` | Bot adapter, e.g. "campfire" |
|
41 | | `--defaults` | Declare all defaults are set and no prompting required |
|
42 |
|
43 | You now have your own functional hubot! There's a `bin/hubot`
|
44 | command for convenience, to handle installing npm dependencies, loading scripts,
|
45 | and then launching your hubot.
|
46 |
|
47 | Hubot needs Redis to persist data, so before you can start hubot on your own computer, you should have Redis installed on your localhost. If just want to test Hubot without Redis, then you can remove `hubot-redis-brain` from `external-scripts.json`.
|
48 |
|
49 | % bin/hubot
|
50 | Hubot>
|
51 |
|
52 | This starts hubot using the [shell adapter](./adapters/shell.md), which
|
53 | is mostly useful for development. Make note of the name in the `hubot>` prompt;
|
54 | this is the name your hubot will respond to with commands. If the prompt
|
55 | reads `myhubot>` then your commands must start with `myhubot <command>`
|
56 |
|
57 | For example, to list available commands:
|
58 |
|
59 | % bin/hubot
|
60 | myhubot> myhubot help
|
61 | myhubot> Shell: myhubot adapter - Reply with the adapter
|
62 | myhubot animate me <query> - The same thing as `image me`, except adds a few parameters to try to return an animated GIF instead.
|
63 | myhubot echo <text> - Reply back with <text>
|
64 | myhubot help - Displays all of the help commands that Hubot knows about.
|
65 | myhubot help <query> - Displays all help commands that match <query>.
|
66 | myhubot image me <query> - The Original. Queries Google Images for <query> and returns a random top result.
|
67 | myhubot map me <query> - Returns a map view of the area returned by `query`.
|
68 | myhubot mustache me <url|query> - Adds a mustache to the specified URL or query result.
|
69 | myhubot ping - Reply with pong
|
70 | myhubot pug bomb N - get N pugs
|
71 | myhubot pug me - Receive a pug
|
72 | myhubot the rules - Make sure hubot still knows the rules.
|
73 | myhubot time - Reply with current time
|
74 | myhubot translate me <phrase> - Searches for a translation for the <phrase> and then prints that bad boy out.
|
75 | myhubot translate me from <source> into <target> <phrase> - Translates <phrase> from <source> into <target>. Both <source> and <target> are optional
|
76 | ship it - Display a motivation squirrel
|
77 |
|
78 | You almost definitely will want to change your hubot's name to add character. bin/hubot takes a `--name`:
|
79 |
|
80 | % bin/hubot --name sam
|
81 | sam>
|
82 |
|
83 | Your hubot will now respond as `sam`. This is
|
84 | case-insensitive, and can be prefixed with `@` or suffixed with `:`. These are equivalent:
|
85 |
|
86 | SAM help
|
87 | sam help
|
88 | @sam help
|
89 | sam: help
|
90 |
|
91 | ## Scripts
|
92 |
|
93 | Hubot'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/hubot-scripts) for `hubot-scripts <your-search-term>`. For example:
|
94 |
|
95 | ```
|
96 | $ npm search hubot-scripts github
|
97 | NAME DESCRIPTION
|
98 | hubot-deployer Giving Hubot the ability to deploy GitHub repos to PaaS providers hubot hubot-scripts hubot-gith
|
99 | hubot-gh-release-pr A hubot script to create GitHub's PR for release
|
100 | hubot-github Giving Hubot the ability to be a vital member of your github organization
|
101 | …
|
102 | ```
|
103 |
|
104 | To use a script from an NPM package:
|
105 |
|
106 | 1. Run `npm install --save <package-name>` to add the package as a dependency and install it.
|
107 | 2. Add the package to `external-scripts.json`.
|
108 | 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.
|
109 |
|
110 | You can also put your own scripts under the `scripts/` directory. All scripts placed there are automatically loaded and ready to use with your hubot. Read more about customizing hubot by [writing your own scripts](scripting.md).
|
111 |
|
112 | ## Adapters
|
113 |
|
114 | Hubot uses the adapter pattern to support multiple chat-backends. Here is a [list of available adapters](adapters.md), along with details on how to configure them.
|
115 |
|
116 | ## Deploying
|
117 |
|
118 | You can deploy hubot to Heroku, which is the officially supported method.
|
119 | Additionally you are able to deploy hubot to a UNIX-like system or Windows.
|
120 | Please note the support for deploying to Windows isn't officially supported.
|
121 |
|
122 | * [Deploying Hubot onto Azure](./deploying/azure.md)
|
123 | * [Deploying Hubot onto Bluemix](./deploying/bluemix.md)
|
124 | * [Deploying Hubot onto Heroku](./deploying/heroku.md)
|
125 | * [Deploying Hubot onto Unix](./deploying/unix.md)
|
126 | * [Deploying Hubot onto Windows](./deploying/windows.md)
|
127 |
|
128 | ## Patterns
|
129 |
|
130 | Using custom scripts, you can quickly customize Hubot to be the most life embettering robot he or she can be. Read [docs/patterns.md](patterns.md) for some nifty tricks that may come in handy as you teach your hubot new skills.
|