Butler in 5 minutes

This Quickguide
This quickguide aims at allowing you to get, install and start a Butler IRC bot without prior knowledge. The green links are glossar-links. If you don't understand an instruction due to such a word, click on the glossary link, it contains more information about that topic.
Formattings
Every thing that means something different is formatted in a different style. A list of all styles can be found here.
Prerequisites
In order to install and run Butler, we need ruby in version 1.8 or higher. You can test that running the following command in your shell:
ruby -v
If you're missing ruby, visit ruby-lang.org.
Another prerequisite is rubygems. If installed, an executable named gem is present. Else, there's an instruction on how to install it.
Install
The next step is installing Butler, it is as simple as typing:
sudo gem install butler
This will install the gem, which means the libraries and botcontrol. Unfortunately RubyGems has no post-install hooks, so we have to do:
sudo botcontrol setup
This will ask you where you want your configuration and stores that value into the global configuration, which is what it needs the sudo for.
It will also ask you where you want your bots and pidfiles stored. Those values are stored in the configuration location you gave and should not require sudo to be changed later.
Setup & run
Now we set up a bot instance and let it run. Butlers layout is so, that your main application is botcontrol. With that application you can create new bots, start existing bots, add/edit/delete users and privileges and all kinds of other stuff. To create a new bot, you do:
botcontrol quickcreate botname
Of course you can choose any name. For the course of this quickguide, we will refer to the created bot as 'butler' (lowercase, in contrast to 'Butler', the whole). Botcontrol will ask you all necessary questions to be able to launch it for the first time. All defaults are set up so that butler would connect to irc.freenode.org#butler. To start the newly created bot, type:
botcontrol start -i butler
If you chose to name your but differently than 'butler', use the appropriate name. You can create any number of bots.
The -i flag lets botcontrol run your bot printing everything to STDOUT, not daemonizing. Just omit it if you want the bot to run in the background.
Testing it
To get Butler to do what you want from him you have to authorize yourself to it.
The dialog will look as following (assuming your bots nick is 'butler', replace with the nickname you actually assigned him), where username and password are what you provided as username and password for the admin in the 'botcontrol create butler' command:
/msg botname login username password
botname: You are now authenticated.
The 'You are now authenticated' confirms that your login was successful. You now are allowed to use all commands butler offers. For example you can try the simplest:

If you use butler on networks which prohibit private message - like freenode for example - you have to register your bots nickname to see the 'You are now authenticated', since otherwise the irc server will prohibit the message from being delivered.
Also if you try to authenticate somewhere else than via a private query, butler will log you in, deactivate your password and ask you to set it to a new one.

yournick: botname ping
 botname: pong
Useful commands are 'help', 'usage' and 'about'.
To manage your plugins (load/unload/list), use the command 'plugins'.
What now?
The next steps depend on how you intend to use butler. If you want to write plugins, then there's a plugin tutorial. To get a more thorough information on how to use butler, consult the manual.

Valid XHTML, 2008-21-05 21:22 CEST