3 Heikki Hokkanen <hoxu@users.sf.net>
9 NOTE: At the time of this writing, Supybot version is 0.83.3. If you are using a newer (or even older) version, keep that in mind.
11 NOTE: This document is very much a work in process. It covers nowhere near everything there is to Supybot. However, it hopefully allows a good start into learning Supybot.
13 === What is this document? ===
15 This document is a handbook for http://supybot.com/[Supybot], the IRC (http://en.wikipedia.org/wiki/Internet_Relay_Chat[Internet Relay Chat]) bot written in Python.
17 === Motivation behind this document ===
19 Some time ago I started needing an IRC bot for various purposes. The bot would have to be able to take care of auto-opping and similar "traditional" channel duties. This made me think of http://oer.equnet.org/[Oer], an old but very nice bot. However, I also wanted to have factoid functionality similar to http://blootbot.sourceforge.net/[blootbot]/http://infobot.org/[infobot], without having to run multiple bots. That was when I arrived at Supybot once again. This time I decided to give it a closer look.
21 My experience of the documentation was lacking though. I longed for something similar to http://oer.equnet.org/um.php[Oer's User Manual] that provides a quick references for basic administrator tasks and so forth. Alas, I could not find such document.
23 I figured I could as well wrap up such a handbook while learning to use the bot myself. Hopefully someone finds reading this document as useful as writing it was.
25 === Conventions used in this document ===
27 `command <name> [value]`::
28 A command that takes `name` as a required parameter and `value` as an optional parameter.
31 A command that takes one or more parameters.
33 `command [--{foo,bar}] <value>`::
34 A command that takes two optional options as parameters, eg. `--foo value` and/or `--bar value`.
39 === This document is Free ===
41 This document is Free (TM) as defined by the http://www.fsf.org/[Free Software Foundation], more specifically, this document is available under the terms of http://www.gnu.org/licenses/gpl-3.0.txt[GNU General Public License version 3 (GPLv3)]. The source is a text file that can be converted to various formats by http://www.methods.co.nz/asciidoc/[asciidoc].
43 === How to give feedback ===
45 If you spot an error, have suggestions or just want to tell me how much you love/hate the document, send e-mail to mailto:hoxu@users.sf.net[]. Prefix the Subject with `[supybook]`.
49 === Initial configuration ===
51 Create a new directory (eg. `mkdir ~/supybot`) and run `supybot-wizard` in it. Follow the directions to get the bot initially configured.
53 Once you are ready with the wizard, I suggest you start the bot inside screen:
60 This way you can attach to the screen later to see the messages it writes to stdout, while still running the bot in the background. Alternative is to run it in the daemon mode, `supybot --daemon configFile`.
62 You can set up a crontab to start the bot automatically, for example:
65 > @reboot screen -d -m supybot /path/to/configFile
68 === Identifying to the bot ===
70 After running supybot-wizard and starting the bot, connect to the same IRC network it is on, and /query it. You can identify with the `identify <name> <password>` command. You can check the bot's idea of who you are with the `whoami` command.
72 NOTE: All commands that contain a `password` must be sent to the bot in private.
74 === Accessing the online help ===
76 Most commands on the bot have a short online help available. You can use `list` to list loaded plugins, and `list <plugin>` to list commands in those plugins. `help [plugin] <command>` can be used to access the command help. Use `more` to read long messages from the bot.
78 Help for configuration items can be accessed with the `config help <key>` command.
80 == Understanding supybot's peculiarities ==
82 Supybot has a couple of features that sets it apart from more traditional bots. More specifically, nested commands, plugin framework (even the basic functionality is implemented using plugins), and capabilities. This section covers some basic information about Supybot. Feel free to skip it, but come back later if you run into something you don't understand.
84 === Nested commands ===
86 Supybot allows nested commands, in other words, you can pass the result of a command to another command as a parameter. What does this allow then, though, apart from the obvious bragging rights? For example, if you want to restore a configuration entry to the default value, you can type:
88 `config reply.withNickPrefix [config default reply.withNickPrefix]`
90 Obviously, that wasn't very neat. They could've included a `config reset <key>` command instead, for example. But I'm sure you can figure out *something* more useful to do with this, as a homework ;-)
94 Pretty much everything in Supybot is a plugin. Most commands you use belong to a plugin. If two plugins provide the same command, then you need to prefix the command with the plugin name. For example, the `ignore list` command yields the following output:
98 Error: The command "ignore list" is available in the Admin and Channel plugins.
99 Please specify the plugin whose command you wish to call by using its name as a command before "ignore list".
102 Thus, you need to either use `admin ignore list` or `channel ignore list` command. That is, unless you define which plugin is the default one using the `defaultplugin [--remove] <command> [plugin]` command provided in the [green]#Owner# plugin.
104 The `list` command ([green]#Plugin#) can be used to list loaded plugins. You can prevent some plugins from showing in the list with the command:
106 `config plugins.<plugin>.public False`
108 WARNING: This does not really make the plugins private. They can still be listed by unregistered users (unless they have anticapability for `list`). This is a bug in my opinion.
111 List currently loaded plugins, excluding the ones set non-public.
114 List loaded plugins that are set to non-public.
117 List commands provided by the given plugin.
119 `load [--deprecated] <plugin>`::
120 Load a plugin. Supybot looks for plugins in directories listed in `config conf.supybot.directories.plugins`. Use comma as a separator.
123 Unloads a plugin. The [green]#Owner# plugin cannot be unloaded.
125 NOTE: Plugins can store information in a database. By default, the database is channel-specific. This can be changed by modifying `config databases.plugins.channelSpecific` to be global. The config item can also be set on per-channel basis.
127 [[installing_plugins]]
128 ==== Installing additional plugins ====
130 To install a third-party plugin, you need first need to copy the plugin in one of the directories listed in `conf.supybot.directories.plugins` (`~/supybot/plugins/` for example). Then you simply `load <plugin>`.
135 git clone git://github.com/jamessan/Supybot-Weather.git Weather
138 NOTE: The plugin directory name under the plugins directory must match the plugin name. In the example above, both "Weather" and "weather" as directory names work, but Supybot-Weather does not.
140 === Configuration ===
142 Most of Supybot configuration is done online using the [green]#Config# plugin. This excludes things such as granting the owner capability (must be done by modifying the files).
144 There are two types of configuration items: global and channel-specific. The latter are actually no different from the global ones, except that they can be set for channels as well. This means you can have a global default which is overridden for specific channels.
146 Configuration items are hierarchical. The "root" item is `supybot`, which can be omitted. Configs for plugins live under their own key, `supybot.plugins`, or shortly, `plugins`.
148 `config <name> [value]`::
149 Get the current value of `name`, or set it to `value` if provided.
151 `config channel [channel] <name> [value]`::
152 Ditto, but for channel configs.
154 `config default <name>`::
155 Get the default value of `name`. This does not change the value. No, there is no command to reset an item to default value. You need to use `config <name> [config default <name>]` for that.
157 `config export <filename>`::
158 Export non-confidential parts of configuration to a file for debugging purposes.
160 `config help <name>`::
161 Show help for a configuration item.
163 `config list <group>`::
164 List configuration items in `group`. Subgroups are prefixed with '@', channel-specific items with '#'.
167 Reloads configuration. Mostly useful if you've had to modify the files by hand.
169 `config search <word>`::
170 Show configuration items matching `word`.
173 Save configuration changes to disk. This should be done automatically as well, if the `flush` configuration item is True (the default).
175 NOTE: Some of the sections in this document have a list of related configuration items. They are listed similarly to the table below. In this example the config value could be modified with the `config plugin.example.foo <True|False>` command. If the key is prefixed with `#`, the config value can be set both globally and on channel-specific basis.
179 Key,Default,Description
181 foo,True,Example key.
182 #bar,False,Example key that can be set on channels as well.
188 Many traditional IRC bots manage permissions of users using flags. Some network services in fact, do, too. Each user can have various flags on each channel. The flags can mean auto-op, op, use of !ban command and so forth. On side of those, there are often global user flags that entitle the user to full access, global auto-op, etc. Some bots also support channel flags that determine what bot functionality is available on the channel.
190 Supybot does not have any flags. Instead, the permissions are managed using 'capabilities'. There are two kinds of capabilities: `user capabilities` and `channel capabilities`.
192 'User capabilities' are checked first when a user tries to run a command. If the user has an 'anticapability' for the command (eg. `-command`, `-Plugin.command`) or the Plugin (`-Plugin`), it won't be run.
194 Next, if the command was run on the channel, the 'channel capabilities' are checked. The logic is same as above, but the checked capabilities are prefixed with `#channel,`, for example `#channel,-Plugin.command`.
196 There are some special capabilities recognized by Supybot:
199 For bot owners: the people who have "physical" access to the bot and its files. This cannot be granted online; the 'conf/users.conf' file must be edited by hand followed by `reload`. Owners are exempt from `#channel,op` capability checks and channel anticapabilities.
202 For bot administrators. Users with this capability can manage global bot properties, make the bot join new channels and so forth. However, they can't do channel administration which is reserved for ops.
205 Channel ops can execute channel-related commands.
208 Allow user to run commands that can potentially crash the bot, or cause denial of service on the system it's running on.
210 Commands used to manipulate capabilities are covered in the <<channel-capabilities,Manipulating channel capabilities>> and <<user-capabilities,Manipulating user capabilities>> sections.
212 == Administrative tasks ==
216 Related plugins: [green]#Network, Services#.
218 ==== Adding a network ====
220 `network connect [--ssl] <network> [<host[:port]>] [password]`::
221 Connect to `network`. `host` must be provided if the network is new or has no servers defined.
223 ==== Reconnecting ====
225 `reconnect [network] [message]`::
226 Disconnects and connects `network`, or current if not specified. `message`, if given, is shown as the quit message, otherwise `config plugins.Owner.quitMsg` is used, or your nickname.
228 ==== Disconnecting ====
230 `network disconnect [network] [message]`::
231 Disconnect `network`, or current if not specified. `message` as above.
233 ==== Listing networks ====
236 List of networks & servers currently connected to.
240 freenode: wolfe.freenode.net and ircnet: irc.elisa.fi
243 `config list networks`::
246 ==== Adding more servers ====
248 Once you've added a network with the initial server, you can add more servers:
250 `config networks.<network>.servers [config networks.<network>.servers] server:6667`
252 ==== Listing network servers ====
254 `config networks.<network>.servers`
258 chat.freenode.net:6667
261 ==== Services: NickServ ====
263 WARNING: My pratical experience with [green]#Services# plugin on Freenode is... not-so-good. It definitely does not work all the time as expected.
265 You can make Supybot identify itself to the network NickServ after it has connected.
267 `config plugins.Services.noJoinsUntilIdentified True`::
268 Settings this is useful on Freenode and other networks who change the user mask after identifying to NickServ. In my experience this seems to be a tad buggy, so I don't recommend enabling it unless really needed.
270 `config plugins.Services.NickServ NickServ`::
271 Tell the bot what name NickServ can be found under.
273 `services password <nick> [password]`::
274 Can be used to set or remove NickServ password.
276 NOTE: Password removal did not work for me on Supybot 0.83.3
278 `services identify`::
279 Identifies the bot to NickServ with the current nick. You don't need to give this command after the bot has been set up; it will identify when connecting to the network automatically.
281 ==== Services: ChanServ ====
283 You can make Supybot request op after joining a channel on a network with ChanServ.
285 `config plugins.Services.ChanServ ChanServ`::
286 Tell the bot what name ChanServ can be found under.
288 `config plugins.Services.ChanServ.op <on|off>`::
289 Set the default for all channels. This will be used unless a channel-specific config overrides it.
291 `config channel [channel] plugins.services.ChanServ.op <on|off>`::
292 Set to request op on the given `channel`.
294 Voice and half-op (on networks supporting it) can be used similarly.
298 Related plugins: [green]#Channel#.
300 NOTE: Commands in this section (such as adding/removing channels) work in the current network, eg. the one you are messaging the bot in. The commands also accept a `[channel]` parameter which is needed only when the command is written in private.
302 NOTE: If you want to /msg the bot in one network, while having the command apply in another network, you can use the `network command <network> <command> [params]` command. The reply comes in the other network if you are there as well.
304 WARNING: The `network command` command does not seem to check if the user having your nick in the other network is recognized (eg. identified or recognized by hostmasks), so the reply may end up to someone else.
306 ==== Adding a new channel ====
308 `join <channel> [key]`::
309 Joins the `channel` using `key` if provided. Channels are automatically remembered and joined when the bot connects to the network next time.
311 NOTE: `config plugins.Channel.alwaysRejoin` determines whether the bot will (attempt to) rejoin the channel when kicked out (the default).
313 ==== Listing channels ====
317 NOTE: This only works in private, to prevent knowledge of top secret channels from falling into wrong hands.
319 You can list channels in another network with `config networks.<network>.channels`. Or with `network command <network> channels`.
321 ==== Removing a channel ====
323 `part [channel] [reason]`::
324 Makes the bot leave `channel`, showing `reason` as part message if given. Note that all channel data is retained, but the bot does not join the channel anymore the next time it connects to the network.
326 ==== Modifying channel config ====
328 `config channel [channel] <name> <value>`::
329 Sets config item `name` on `channel` to `value`, overriding the global value.
331 ==== Setting the key ====
333 `channel key [channel] [key]`::
334 Sets key on `channel` to `key`, or removes it if `key` is not given.
336 ==== Setting the limit ====
338 `channel limit [channel] [limit]`::
339 Sets limit on `channel` to `limit`, or removes it if `limit` is not given (or is zero).
341 ==== Channel commands ====
343 Channel ops can use the following commands to control the channel via the bot, assuming it is opped.
345 `op [channel] [nick...]`::
346 Ops the given nicks (or you if none) on the channel.
348 `deop [channel] [nick...]`::
351 `voice [channel] [nick...]`::
352 Voices the given nicks (or you if none) on the channel.
354 `devoice [channel] [nick...]`::
357 `kban [channel] [--{exact,nick,user,host}] <nick> [seconds] [reason]`::
358 Bans and kicks the given nick from the channel. If `seconds` is specified and is not 0, the ban will expire after that time.
360 `mode [channel] <mode> [params]`::
361 Set channel mode. This can be used to change any channel modes, making the commands below redundant aliases.
363 `moderate [channel]`::
364 Set +m. This is not enforced by the bot, so any channel op can remove it.
366 `unmoderate [channel]`::
369 `topic lock [channel]`::
370 Set +t. Not enforced, so any channel op can remove it.
372 `topic unlock [channel]`::
375 `alert [channel] <text>`::
376 Sends `text` to all users on the channel with op capability.
379 Make the bot part and join the channel. Mostly useful to test whether auto-ops from other bots/users work for the bot.
381 ==== Maintaining the ban list ====
383 `ban add [channel] <nick|hostmask> [expires]`::
384 Add ban for given nick or hostmask on the channel. If nick is given, the full hostmask is banned. `expires` when gives, expires the ban after so many seconds.
386 `ban list [channel]`::
387 List bans with their expire times.
389 `ban remove [channel] <hostmask>`::
390 Removes the ban on given `hostmask`.
392 `config plugins.Channel.banmask <string>`::
393 Hostmask style for `ban add`: `exact`, `nick`, `user`, `host`. This means which parts of the nick's current hostmask are used (rest are wildcarded). Default is `host user` (eg. `*!user@host`).
395 NOTE: Users matching the ban list are not automatically kicked off the channel. See the `kban` command in the previous section to kick and ban a user.
397 ==== Maintaining the ignore list ====
399 `channel ignore add [channel] <nick|hostmask> [expires]`::
400 Ignores `hostmask` (or the full hostmask `nick` currently has) on `channel`. If `expires` is given, the ignore expires after that many seconds.
402 `channel ignore list [channel]`::
403 Show ignored hostmasks on `channel`. This does not show the expire times, though (argh!).
405 `channel ignore remove [channel] <hostmask>`::
406 Remove `hostmask` from list of ignored hostmasks on `channel`.
408 NOTE: There is also a global ignore list, available for admins.
410 ==== Listing channel nicks ====
412 `channel nicks [channel]`
414 ==== Topic operations ====
416 Related plugins: [green]#Topic#.
418 Supybot allows elaborate manipulation of the channel topic. Topic consists of items, separated by a configurable character (default is `||`). Items are one-indexed.
420 People who have used the Oer bot may notice that the topic manipulation commands are http://oer.equnet.org/help.php#um39[somewhat similar].
422 `topic add [channel] <text>`::
423 Add a new topic item at the end.
425 `topic change [channel] <number> <regexp>`::
426 Do a regular expression substitution on the topic item `number`. For example: `topic change 2 s/foo/bar/`.
428 `topic default [channel]`::
429 Restore topic on channel to the default set with `config plugins.Topic.default`.
431 `topic fit [channel] <text>`::
432 Adds a new topic item at the end like `topic add`, but if there isn't enough space, first removes some items from the beginning. `topic add` complains if there isn't enough space.
434 `topic get [channel] <number>`::
435 Return topic item `number`.
437 `topic insert [channel] <text>`::
438 Add a new topic item in the beginning.
440 `topic list [channel]`::
441 Return list of topic items.
443 `topic lock [channel]`::
444 Set channel mode `+t`, preventing non-opped users from changing the topic.
446 `topic redo [channel]`::
449 `topic remove [channel] <number>`::
450 Remove item `number` from the topic.
452 `topic reorder [channel] <number>...`::
453 Reorder topic items in the given order. You must give as many numbers as there are items. For example, to move third item to first position, use `topic reorder 3 1 2`.
455 `topic replace [channel] <number> <text>`::
456 Replace topic item `number` with `text`.
458 `topic restore [channel]`::
459 Revert any changes made to the topic by users, and set it back to whatever the bot last set it to.
461 `topic separator [channel] <separator>`::
462 Change the topic separator to `separator`.
464 `topic set [channel] [number] <text>`::
465 Replace either the whole topic or, if `number` is given, one item. In the latter case, this is the same as `topic replace`.
467 `topic shuffle [channel]`::
468 Reorder the topic items randomly.
470 `topic swap [channel] <number1> <number2>`::
471 Swap topic items at the given positions.
474 Show (the whole) topic for the channel.
476 `topic undo [channel]`::
477 Revert the last change a topic command made to the topic. Note that if users directly edited the topic, those changes will be lost. Can be used multiple times.
479 `topic unlock [channel]`::
480 Set channel mode `-t`, allowing all users to change the topic.
485 Key,Default,Description
487 #default,,Default channel topic
488 #format,$topic ($nick),Format for the items
489 #recognizeTopiclen,True,Whether to recognize max topic length given by the server and refuse to set longer topics.
490 #separator,||,Used to concatenate items
491 #undo.max,10,How long undo history to keep
494 .Aliases for partial oer compatibility:
496 alias add ta topic add $1
497 alias add td topic delete $1
498 alias add te topic replace $1 $2
499 alias add ts topic swap $1 $2
504 Logging of channels is provided by the [green]#ChannelLogger# plugin. Various channel-specific configuration items are provided, see `config list plugins.ChannelLogger`.
506 By default logs will go into logs/ChannelLogger/<network>/<channel>/<channel>.log and will be rotated when the default "%d-%a-%Y" (eg. 06-Sat-2008) timestamp rotates. See http://docs.python.org/lib/module-time.html[the python documentation for strftime] for the formatting characters.
508 NOTE: The logs of [green]#ChannelLogger# cannot be searched online. However, other plugins provide some searching functionality. See <<searching-history,Searching the history>>.
510 ==== Auto-ops and voices ====
512 Auto-opping is provided by the [green]#AutoMode# plugin.
515 Loads the [green]#AutoMode# plugin, which works out-of-box. By default it's enabled on all channels and voices/halfops/ops users with respective capabilities. You can enable auto-opping only on some channels by tweaking the config keys below.
520 Key,Default,Description
522 #enable,True,Whether the plugin is enabled.
523 #fallthrough,False,"If enabled and `op` is False, halfops/voices instead if they are True."
524 #halfop,True,Halfop users with the `halfop` capability.
525 #op,True,"Ditto, but op."
526 #voice,True,"Ditto, but voice."
527 #ban,True,Whether to ban people who join the channel and are on the banlist.
528 #ban.period,86400,How many seconds bans will last.
531 [[channel-capabilities]]
532 ==== Manipulating channel capabilities ====
534 `capability list [channel]`::
535 List capabilities on `channel`.
537 `capability set [channel] <capability..>`::
538 Adds the given `capability` to `channel`.
540 `capability unset [channel] <capability..>`::
541 Removes the given `capability` from `channel`.
543 `capability setdefault [channel] <True|False>`::
544 Whether to allow users on `channel` by default to access non-maintenance related commands. Default is True.
546 Note that this concerns unregistered users as well. So if you want to disallow use of commands by unregistered users, set default user capabilities to allow them, and set this to False.
548 See also <<capabilities,Capabilities>>.
552 Related plugins: [green]#Users#.
554 Supybot users are global: they are visible across networks. This means the same username/password and hostmasks will work in all networks the bot is on.
556 Users are recognized either by matching hostmasks, or after manually identifying to the bot. In secure mode, the user must both match a hostmask and identify to the bot (`uset set secure [password] <True|False>`).
558 NOTE: If users knowing each others' nicks is an issue, they could come up with different aliases when registering to the bot. The bot username does not have to match the nick of the user.
560 ==== Adding a new user ====
562 `user register <name> <password>`
564 ==== Manipulating hostmasks ====
566 `user hostmask add` - add your current hostmask. Obviously this makes only sense after identify.
568 `user hostmask add [name] [hostmask] [password]` - add hostmask for another user. If not owner, password must be given.
570 `user hostmask remove <name> <hostmask> [password]`
572 NOTE: There is no way to add network-specific hostmasks.
574 ==== Listing users ====
576 `user list [glob]` - list registered users. Note that the list of users is global across networks.
578 ==== Deleting users ====
580 `user unregister <name> [password]`
582 ==== Changing password ====
584 `user set password <user> <old password> <new password>`.
586 ==== Renaming a user ====
588 `user changename <name> <new name> [password]`
590 Users can change their name themselves.
592 [[user-capabilities]]
593 ==== Manipulating user capabilities ====
595 `capabilities [user]`::
596 List capabilities of the `user`, or the calling user.
598 `admin capability add <user|hostmask> <capability>`::
599 Add `capability` to `user` or a user that matches the `hostmask`.
601 `admin capability remove <user|hostmask> <capability>`::
602 Ditto, but remove the capability.
604 `channel capability add [channel] <nick|user> <capability..>`::
605 Add capability `capability` on `channel` to `nick`/`user`.
607 `channel capability remove [channel] <nick|user> <capability..>`::
608 Remove capability `capability` on `channel` from `nick`/`user`.
610 `defaultcapability <add|remove> <capability>`::
611 Add or remove `capability` from list of capabilities given to new users.
613 `config capabilities`::
614 List default capabilities given to new users.
618 -owner -admin -trusted
621 See also <<capabilities,Capabilities>>.
623 === General bot maintenance ===
625 Related plugins: [green]#Admin, Config#.
627 ==== Setting nickname & alternative nick ====
629 `admin nick <newnick>`::
630 Change nick to `newnick`.
635 `config nick.alternates`::
636 Space-separated list of alternate nicks, %s refers to nick.
638 NOTE: It is not possible to have a different nick in different networks.
640 ==== Setting ident ====
642 `config ident <newident>`::
643 Sets the bot's ident (`nick!ident@host`).
645 ==== Setting ircname ====
647 `config user [ircname]`::
648 Sets the bot's ircname/realname to `ircname`. If left empty, defaults to 'Supybot 0.83.3' for example.
650 ==== Setting command prefix / controlling when the bot replies ====
652 Like most other bots, the bot can be addressed by its nickname, or a command prefix character (any or many of `~!@#$%^&*()_-+=[{}]\|'";:,<.>/?`). For special (braindead?) purposes the bot can also be made assume that all lines are addressed to it.
654 `config reply.whenAddressedBy.chars`::
655 List of characters the bot will recognize as addressing, besides the nick of the bot.
657 `config channel [channel] reply.whenAddressedBy.chars`::
658 Ditto, but for a specific channel.
660 `config reply.whenNotAddressed`::
661 Assume everyone wants to talk to the bot, eg. treat all messages as if addressed to the bot. This does not imply `reply.WhenNotCommand False` which you should set as well.
663 `config reply.whenNotCommand`::
664 Whether to reply when addressed with an invalid command.
666 See also: <<config_reply,Configuration: reply>>.
668 ==== Keeping the primary nick ====
670 Like other bots, Supybot can be configured to try and keep the primary nick using the [green]#NickCapture# plugin. This is primarily useful in networks with no NickServ support.
673 Loads the plugin which works without further configuration.
675 `config plugins.NickCapture.ison`::
676 Whether the plugin is actively checking for the primary nick. This setting makes no sense, as you might as well `unload NickCapture` if you think about setting this to false.
678 `config plugins.NickCapture.ison.period`::
679 How many seconds to wait between nick availability polls. The default is 600 (10 min). The smaller you set this, the higher the chance of the bot recovering the nick when it becomes available. On the other hand, you will also generate more traffic so you might want to avoid that.
681 === Owner commands ===
683 `owner announce <text>` - send `text` to all channels the bot is on.
685 `owner ircquote <raw>` - send `raw` as-is to the server. You need to know your way around http://www.faqs.org/rfcs/rfc1459.html[RFC1459] pretty well to use this.
689 [[searching-history]]
690 === Searching the history ===
692 `url last [channel] [--{from,with,without,near,proto} value] [--nolimit]`::
693 Find last URL (or all with `--nolimit`) matching given criteria. From matches nick, with(out) part of the URL, near rest of the line where the URL was, and proto matches the protocol (https, ftp, etc). In case of multiple URLs, the newest is listed first. Multiple criterias can be given.
695 NOTE: This command lists only the URLs, not nick or what message the URLs were part of. No date is shown either.
697 `last [--from,in,on,with,without,regexp} value] [--nolimit]`::
698 Find messages matching given criteria. From matches nick, in matches channel, on matches network, with(out) matches part of the message, regexp matches messages that are included by the regular expression. Also see `config protocols.irc.maxHistoryLength`.
700 === Useful plugins ===
705 Alias is one of the most powerful plugins available in Supybot. It allows you to set up 'shortcuts' to other commands. When put together with command nesting, and the ability to provide arbitrary number of required and optional arguments to each alias, this becomes a very versatile feature. The main commands in this plugin are `add` and `remove` to add and remove aliases:
707 `add <name> <alias>`::
708 Defines an alias `name` that executes `alias`. The `alias` should be in the standard "command argument [nestedcommand argument]" arguments to the alias; they'll be filled with the first, second, etc. arguments. $1, $2, etc. can be used for required arguments. @1, @2, etc. can be used for optional arguments. $* simply means "all remaining arguments," and cannot be combined with optional arguments.
711 Removes the alias named `name`.
713 As a simple example, let's say you want to set up a quick check to see if some website is down, using the downforeveryoneorjustme.com service. See the following example session for how you'd accomlish that:
716 <user> alias add isitdown web title http://downforeveryoneorjustme.com/$1
717 <supybot> The operation succeeded.
718 <user> isitdown google.com
719 <supybot> It's just you.
722 What this has accomplished is that you don't have to give the full command, which would be `web title http://downforeveryoneorjustme.com/google.com`, instead you now have a quick shortcut to check the status of a site. Aliases get their own help messages, just like all the normal commands, which tell us what got stored in the alias. For example, for the alias above:
726 <supybot> (isitdown <an alias, 1 argument>) -- Alias for "web title http://downforeveryoneorjustme.com/$1".
729 We have introduced the variable substitution feature of aliases here. Note the `$1` in the alias, which means "put the first argument provided to this command right here". You can also have optional arguments, which are represented as `@1`, `@2`, etc. There is also `$*` which acts as a placeholder for "all the remaining arguments", but it cannot be mixed with optional arguments. For example, we can try the following:
732 <user> alias add saymoo echo moo $1 @1
733 <supybot> The operation succeeded.
735 <supybot> (saymoo <an alias, at least 1 argument>) -- Alias for "echo moo $1 @1".
738 <user> saymoo bla stuff
739 <supybot> moo bla stuff
742 There are some important details to understand when you use nested commands and quotes in your aliases. For example, you might naively try the following:
745 <user> alias add test echo [uptime]
746 <supybot> The operation succeeded.
748 <supybot> (test <an alias, 0 arguments>) -- Alias for "echo I have been running for 1 day, 14 hours, 46 minutes, and 53 seconds.".
751 Notice what happened - the uptime command was executed, then stored into the alias, rather than the actual command nesting getting stored. Every time you call the test command, the output will always be exactly the same. This is probably not what you had in mind. To avoid immediate nested command evaluation, you must put quotes around the argument to alias (or around the argument to echo). Like so:
754 <user> alias add test "echo [uptime]"
755 <supybot> The operation succeeded.
757 <supybot> (test <an alias, 0 arguments>) -- Alias for "echo [uptime]".
759 <supybot> I have been running for 1 day, 14 hours, 50 minutes, and 19 seconds.
764 Another issue we'll want to address is, what if you want literal quotes in your alias output? For example, say you want an alias that would give the following output:
768 <supybot> bla "moo" bla
771 We are going to use the `echo` command from the 'Utilities' plugin, which lets the user make the bot say any string. Our first naive try may be the following:
774 <user> alias add test echo bla "moo" bla
775 <supybot> The operation succeeded.
777 <supybot> (test <an alias, 0 arguments>) -- Alias for "echo bla moo bla".
779 <supybot> bla moo bla
782 Doesn't work. The quotes are simply taken as quoting an argument, and don't make it into the alias. Let's try escaping the quotes and see what happens.
785 <user> alias add test echo bla \"moo\" bla
786 <supybot> The operation succeeded.
788 <supybot> (test <an alias, 0 arguments>) -- Alias for "echo bla \"moo\" bla".
790 <supybot> bla \"moo\" bla
793 Closer, but still no cigar - this is because of the way supybot argument parsing works - unquoted arguments get taken as string literals, while quoted arguments get string parsing done on them. Compare the two outputs below:
798 <user> echo "bla\"bla"
802 Raw unquoted string is taken as a literal, while the quoted string interprets the `\"` sequence as an escaped quote character. This is what we want. Our goal is, then, to get the string `echo "bla \"moo\" bla"` as the content of our alias.
804 Our final, successful, try follows:
807 <user> alias add test "echo \"bla \\\"moo\\\" bla\""
808 <supybot> The operation succeeded.
810 <supybot> bla "moo" bla
812 <supybot> (test <an alias, 0 arguments>) -- Alias for "echo "bla \"moo\" bla"".
815 Note what is happening here. First, we quote the entire content of the alias as an argument, to get string parsing going. We escape the quote character before bla, to get a literal quote character into the alias string. We then triple-escape the second quote character. `\\` gets a literal backslash into our alias string, while the following `\"` gets a literal quote. We do the same thing for the closing quotation around `moo`. Finally, we stick in another literal quote to finish quoting the argument to echo, and at the end, close the exterior quotation pair.
817 Quite a bit of detail here - but necessary to know if you're going to be using aliases to perform complex tasks.
822 Allows you to provide users a way to chat on a channel anonymously (eg. only the bot owner(s) know via logs who are talking).
824 `do <channel> <action>`::
825 Sends `action` to `channel`. This is the same as a normal IRC client `/me does something` command.
827 `say <channel> <text>`::
828 Say `text` on `channel`.
832 Key,Default,Description
834 #requirePresenceInChannel,True,Whether the user must be in the channel the message is targeted to.
835 allowPrivateTarget,False,Whether to allow a nick as a target for say. NOTE: This has not been implemented in 0.83.3 although it exists!
836 requireCapability,,"If set, capability to check for."
837 requireRegistration,True,Whether registration is required to use this plugin.
843 [green]#Dict# provides dictionary functionality using dict.org. You can also use a local dictd server.
845 `dict [dictionary] <word>`::
846 Show dictionary entry for `word`, from `dictionary` if provided. If `plugins.Dict.default` is set, use the specified dictionary instead of all.
849 List dictionaries available on the used server.
852 Show a random dictionary from available dictionaries.
854 `config plugins.Dict.server [server]`::
855 The dictd server to be used, default is dict.org.
857 `config plugins.Dict.default [dictionary]`::
858 Channel-specific default dictionary for `dict` command. `*` means to use all dictionaries. `wn` is a good default if english words are mostly looked up.
863 This is a nick-based replacement for NoteServ and the likes. Simply put, you give the bot a note to deliver to a nick (or wildcard) the next time it sees a matching nick. In other words, this can be used to deliver messages to people who are not registered to the bot. Naturally that is not a very safe method of communicating.
866 List nicks that have notes queued, or the notes queued for `nick` if given.
868 `later tell <nick> <text>`::
869 Queues `text` to be sent to first matching `nick` when seen. Nick can contain wildcards, eg. `foo*`.
871 `config plugins.Later.maximum`::
872 How many messages can be queued per nick at maximum, default is 0 = no limit.
874 `config plugins.Later.private`::
875 Whether to send notes in private or on the channel where the recipient is seen.
877 [[plugin_moobotfactoids]]
878 ==== MoobotFactoids ====
880 MoobotFactoids implements nifty factoids.
883 <user> !supybook is <reply> Please read http://supybook.fealdia.org/ before asking.
886 <bot> Please read http://supybook.fealdia.org/ before asking.
891 config databases [config databases] sqlite
895 NOTE: If you get any of the following errors, you need to install sqlite, python-sqlite and python-pysqlite.
898 NoSuitableDatabase: No suitable databases were found. Suitable databases include sqlite.
899 Error: You need to have PySQLite installed to use this plugin. Download it at <http://pysqlite.org/>
905 The [green]#Seen# plugin keeps track of last channel/nick/user activity. Most typical use is asking the bot when a given user was last seen chatting on a channel.
907 `seen any [channel] [--user <user>] [nick]`::
908 Lists any activity given `nick` or `user` was doing on the channel. If no `nick` or `user` is given, returns the last activity on the channel, regardless of who it was from.
910 `seen last [channel]`::
911 Last line said on the channel.
913 `seen [channel] <nick>`::
914 Last time a `nick` was seen on a channel and what it said.
916 `seen user [channel] <user>`:
917 Ditto, except use a user name, disregarding what nick the said user had.
922 The [green]#Web# plugin contains some useful WWW-related functionality, such as fetching titles for URLs users paste on the channel.
925 Show the doctype line of `url`, if any.
928 Show the contents of `url`. Amount of data shown is determined by the configuration variable `plugins.Web.fetch.maximum`.
931 Show web server headers for the `url`.
933 `netcraft <hostname|ip>`::
934 Ask netcraft what OS and web server it thinks the server is running.
937 Show size of `url`, based on the `Content-Length` header sent by the web server.
940 Show title for `url`. This can be done automatically for all URLs pasted on a channel; see the configuration variable `plugins.Web.titleSnarfer`.
943 Return `text` quoted into a URL. Eg. `urlquote foo bar` -> `foo%20bar`.
945 `urlunquote <text>`::
946 Likewise, but reverse.
951 Key,Default,Description
953 #nonSnarfingRegexp,,"if set, URLs matching the pattern are not snarfed."
954 #titleSnarfer,false,Whether to fetch and show the title for pasted URLs.
955 fetch.maximum,0,"Maximum bytes to fetch with the `fetch` command. If zero, `fetch` is disabled."
958 === Entertainment ===
960 [[plugin_channelstats]]
961 ==== ChannelStats ====
963 [green]#ChannelStats# provides channel/registered user statistics (statistics as in 'large numbers').
965 `channelstats [channel]`:
966 Show statistics for `channel`: messages, characters, words, smileys, frowns, actions, joins, parts, quits, kicks, mode changes, and topic changes.
968 `stats [channel] [user]`:
969 Show statistics for `user` on `channel`: messages, characters, words, smileys, frowns, actions, joins, parts, quits, kicks given/received, topic changes, and mode changes.
971 WARNING: This plugin may turn otherwise normal users into spammers. But it can also provide an incentive to register on the bot. :-)
973 .plugins.ChannelStats
976 Key,Default,Description
978 #frowns,`:| :-/ :-\ :\ :/ :( :-( :'(`,Space-separated list of frowns.
979 #selfStats,`True`,Whether to include the bot in the statistics.
980 #smileys,`:) ;) ;] :-) :-D :D :P :p (= =)`,Space-separated list of smileys.
989 `dice <dices>d<sides>`::
990 Roll `dices` dices, each having `sides` sides. Lists result for each dice separately. The sum will be between `dices` and `dices` x `sides`.
992 `eightball [question]`::
993 Answers a question. But don't expect the bot to pass
995 `monologue [channel]`::
996 Check how long your monologue on the `channel` is, in case you are lose count. This is probably my favourite useless command.
998 `roulette ["spin"]`::
999 Russian roulette. If `spin` is given, spins the chambers. This isn't really necessary since it will be done automatically at the end of the round. Provides a different experience if the bot is opped.
1002 [[plugin_nickometer]]
1003 ==== Nickometer ====
1005 `nickometer [nick]`:
1006 Give an objective evaluation on the lameness of `nick`, or your nick if not provided. This is similar to the same command in blootbot.
1010 The "lame nick-o-meter" reading for "1eEteStWaReZL0rD[69X~" is 99.98%.
1016 `quote add [channel] <text>`::
1017 Add `text` as a quote for `channel`.
1019 `quote change [channel] <id> <regexp>`::
1020 Change quote `id` on `channel` using `regexp`. For example, `s/foo/bar/g` changes all instances of `foo` to `bar`.
1022 `quote get [channel] <id>`::
1023 Show quote # `id` for `channel`.
1025 `quote random [channel]`::
1026 Show random quote from `channel`.
1028 `quote remove [channel] <id>`::
1029 Remove quote # `id` from `channel`.
1031 `quote search [channel] [--{regexp,by} value] [glob]`::
1032 Find quotes from `channel` matching regexp if provided, added by nick `by` if provided, and matching `glob` if provided. `glob` may contain wildcards (eg. `foo*bar`), while `regexp` is a regular expression (eg. `/la.*laa/`). Note that you can really provide both regexp and the glob - both must match in that case.
1034 `quote stats [channel]`::
1035 Show how many quotes there are.
1037 [[plugin_quotegrabs]]
1038 ==== QuoteGrabs ====
1040 This plugin allows users to 'grab' the most recent line of another nick as a quote.
1042 `quotegrabs get [channel] <id>`::
1045 `quotegrabs grab [channel] <nick>`::
1046 Save last line from `nick` as a quote.
1048 `quotegrabs list [channel] <nick>`::
1049 List quotes for `nick`, newest first. This does not display full quotes, but part of each, along with the id.
1051 `quotegrabs quote [channel] <nick>`::
1052 Show last quote of `nick`.
1054 `quotegrabs random [channel] [nick]`::
1055 Random quote from any nick, or `nick` if provided.
1057 `quotegrabs search [channel] <text>`::
1058 Show quotes containing `text`. Unfortunately, this does not list the nick or allow searching only given nick's quotes. Id and quote content will be shown.
1063 Key,Default,Description
1065 #randomGrabber,False,Whether to grab random lines as quotes.
1066 #randomGrabber.averageTimeBetweenGrabs,864000,Average number of seconds to wait between random grabs. When half of this has passed a random grab may occur.
1067 randomGrabber.minimumCharacters,8,Minimum characters needed to consider a line eligible for random grab.
1068 randomGrabber.minimumWords,3,"Ditto, but for words."
1071 === Third-party plugins ===
1073 This section lists some useful third-party plugins. See <<installing_plugins,Installing additional plugins>> for how to install third-party plugins. If you feel something is missing from this session, please e-mail the author.
1075 [[plugin_messageparser]]
1076 ==== MessageParser ====
1079 <user> your question is covered in the ,,supybook
1080 <supybot> Follow this link to the supybook, a supybot handbook: http://supybook.fealdia.org/
1082 <user> I'd like a ,,(factoids search *) please
1083 <supybot> 'conditional', 'ggc', 'ggr', 'git', 'gitrepo', 'gribblegitcontent', 'gribblegitrepo'
1086 MessageParser allows adding regular expression triggers that can match any line. Multiple triggers can match a single line, and the same trigger can match several times. This plugin is a very useful addition for support channels.
1088 Visit the http://sourceforge.net/apps/mediawiki/gribble/index.php?title=MessageParser_Plugin[MessageParser wiki] for more information.
1093 Robert Bergermann has written a https://github.com/rbbremen/Twitter4Supybot[Twitter plugin] for Supybot. See https://github.com/rbbremen/Twitter4Supybot/tree/master/Twitter#readme[the readme] for more information.
1098 James McCoy has written a https://github.com/jamessan/Supybot-Weather[Weather plugin].
1101 <user> weather berlin, germany
1102 <supybot> The current temperature in Prenzlauer Berg, Berlin, Germany is -7.1°C (6:13 PM CET on February 01, 2012). Conditions: Clear. Humidity: 25%. Dew Point: -24.0°C. Windchill: -12.0°C. Pressure: 30.66 in 1038.1 hPa (Rising).
1107 This is a list of issues I have not yet figured out how to do, or there simply isn't a way.
1109 - How to enforce channel modes (eg. force +ns-t for example)
1110 - How to delete config items
1111 - How to delete channels / networks
1112 - Ban add does not seem to work on Freenode
1113 - No global ban list
1114 - No way to delete a network
1115 - Incomplete multi-network support
1116 * Capabilities are not network/channel -specific, but channel-specific. If channel by same name exists in two networks, the users have same capabilities on both
1117 * No way to add network-specific hostmasks
1118 * Not possible for the bot to have different nick in different networks
1119 - There is no command to reboot the bot; it must be done from the shell
1120 - Capabilities/anticapabilities for commands with spaces in them are not supported
1124 === How to emulate blootbot CMDs using MoobotFactoids ===
1126 [,yellow]#Thanks to Tobias "beardy" Rosenqvist for the tip!#
1128 We try to make a command factoid, like we are used to with blootbot:
1131 <user> cmdtest is <action> gives $1 "(an apple|a pear)"
1138 <user> cmdtest someone
1141 But it doesn't work.
1142 However, the factoid works:
1146 * bot gives $1 an apple
1149 The Moobotfactoids plugin in supybot doesn't handle arguments, (yet)
1150 unfortunately, so you need to do it another way.
1151 Use the Moobotfactoids to do the random part(s):
1154 <user> fruits is <reply> "(an apple|an orange|a banana|a pear)"
1158 Then use an alias to do the command, with arguments (the "action" command
1159 is found in the Reply plugin), here you also see a use of a nested command:
1162 <user> alias add givefruit action gives "[fruits]" to $1
1164 <user> givefruit someone
1165 * bot gives a pear to someone
1168 === Tidier bot replies ===
1170 I don't personally like the default Supybot replies: I hate the nick prefix and the way too verbose 'The operation succeeded.'.
1172 Fortunately there are plenty of settings to configure how Supybot replies. These can be listed with `config reply` and `config replies`.
1174 The `reply` items determine how Supybot acts, and `replies` contains some messages it uses. I prefer:
1176 `config reply.withNickPrefix False`
1178 `config replies.success OK`
1180 `config reply.error.inPrivate True`.
1182 === More on nested commands ===
1184 [,yellow]#Thanks to Tobias "beardy" Rosenqvist for the tip!#
1186 For those familliar with unix shells, (bash in particular), nested commands can be compared to doing command substitution, as in `$(command)`.
1188 Nested commands are by default enclosed by square brackets (`[]`). The `commands.nested.brackets` configuration variable can be used to set these to `<>`, `{}`, or `()`.
1191 <user> echo The title of the Supybot website is: [web title http://www.supybot.com/]
1192 <bot> The title of the Supybot website is: Welcome to Supybot.com! Supybot Website
1195 Another way nested commands can work, is like a pipe, if the configuration variable `commands.nested.pipeSyntax` is set to `True`.
1197 Same example as above, but using the pipeSyntax:
1200 <user> web title http://www.supybot.com/ | echo The title of the Supybot website is:
1201 <bot> The title of the Supybot website is: Welcome to Supybot.com! Supybot Website
1206 === Configuration ===
1211 *#inPrivate*:: Whether to reply in private to commands given on channel.
1213 *#requireChannelCommandsToBeSentInChannel*:: -
1215 *#showSimpleSyntax*:: Whether to be extra helpful when a user fails syntax of a command.
1217 *#whenNotAddressed*:: Assume everyone wants to talk to the bot, eg. treat all messages as if addressed to the bot. This does not imply `reply.WhenNotCommand False` which you should set as well.
1219 *#whenNotCommand*:: Whether to reply when addressed with an invalid command.
1221 *#withNickPrefix*:: Whether to prefix the reply with the nick of the user who gave the command.
1223 *#withNotice*:: Whether to use notices instead of regular messages.
1225 *#mores.instant*:: How many messages to send initially before prompting for `more`. Default is 1.
1227 *#mores.length*:: How long messages can be. Default is 0, which uses rocket science to determine the maximum number of characters that can be fit into a message without it collapsing into a black hole.
1229 *#mores.maximum*:: Maximum number of messages to queue, default is 50.
1231 *#error.inPrivate*:: Whether to send errors in private instead of replying on channel.
1233 *#error.noCapability*:: If True, don't tell users why they can not run a command because of missing capabilities.
1235 *#error.withNotice*:: Whether to send errors as notices instead of regular messages.
1237 *error.detailed*:: Whether to show an exception or a generic error when something breaks. Mostly useful for developers.
1239 *#format.time*:: Format string for timestamps (`%I:%M %p, %B %d, %Y`, eg. '08:41 PM, September 11, 2008').
1241 *#whenAddressedBy.chars*:: List of characters the bot will recognize as addressing (when a command is prefixed with one of them), besides the nick of the bot.
1243 *#whenAddressedBy.nicks*:: List of extra nicks to consider as addressing the bot, despite the current nick.
1245 *#whenAddressedBy.strings*:: Like the chars key, except a space-separated list of strings to accept as command prefix. This allows multicharacter command prefixes.
1247 *#whenAddressedBy.nick.atEnd*:: Whether to consider messages that end in the bot's nick to be addressed to the bot.
1249 *maximumLength*:: Maximum length of a reply message from the bot. This does not mean the length of a single message (prompting for `more`), but the whole message.
1251 *oneToOne*:: Whether to send replies consisting of multiple messages in a single message.
1253 *withNoticeWhenPrivate*:: Whether to use notices instead of private messages.
1255 === Directory tree ===
1257 This section contains list of the directories and files supybot uses, and what they are for.
1259 NOTE: If you modify the configuration files by hand when the bot is running, you need to run `config reload`.
1262 For backups of config files.
1265 Configuration files: {channels,ignores,userdata,users}.conf
1271 Channel-specific plugin databases.
1274 Temporary plugin data files (eg. database journals).
1279 `logs/ChannelLogger/`::
1280 ChannelLogger logs. The structure depends on the config variables.
1282 `logs/messages.log`::
1286 Local plugin directory. This is by default listed in `config directories.plugins`.
1289 The main configuration file of the bot.