Kibot Commands

All functions can be called by their full path, i.e. modname.cmdname. If only cmdname is typed, it will be searched for in all loaded modules according to the path (see the base.path command).

Some modules can be treated like commands themselves. For example, you can do a google search either with the command google.search your search terms or simply with google your search terms. Such command-like behavior is listed as a command named (call) in the help below.

Some commands require specific permissions in order to be executed. These command permissions (or cperms) are usually a simple name, but can be more powerful.

Modules

Module Description
base base bot functions
auth user and authentication management
irc basic irc operations and channel management
magic The Magic3PiBall: 3 times pi is greater than 8.
acro look up acronyms
whereis find the geographical location of a TLD
rand spew random (and occasionally humorous) stuff
google do google searching
slashdot get notified about slashdot stories
units Convert between standard and english measurements
bugzilla Show a link to a bug report with a brief description
log logging of irc communication
messaging messages, ping notification and user tracking

Module Summaries

base -- base bot functions

Command Description
about give basic bot information
help get help on something
phelp print help to a channel (publicly)
perm find required perms for a command
path view or set the path
which find where a command lives
get get a module setting
set set a module setting
load load a bot module
unload unload a bot module
RELOAD reload a core module
reload reload a bot module
die tell the bot to exit
reconnect tell the bot to reconnect
restart tell the bot to restart fully

auth -- user and authentication management

Command Description
profile print a user's profile
give grant a user permissions
take revoke a user's permissions
authpass authenticate via password
setpass set your password
addmask add a mask to a user's profile
delmask delete mask from a user's profile
meet introduce a user to me
recognize recognize someone as a known user
unrecognize UN-recognize someone
forget forget a known user
users list known users
whois print a user's userid by nick
grants list perms that a user with <perm> can grant
addgrant add <perms> that can be granted by a user with <PERM>
delgrant remove <perms> that can be granted by a user with <PERM>
implies list perms that are implied by <perm>
addimply add <perms> that are implied by <PERM>
delimply remove <perms> that are implied by <PERM>

irc -- basic irc operations and channel management

Command Description
op give ops to someone
kick kick a user from a channel
invite invite a user to an invite-only channel
channels list channels
join tell the bot to join a channel
nick tell the bot to change nicks
part tell the bot to leave a channel
oper tell the bot to become an IRCop
mode execute a raw MODE command
raw send raw text to the irc server

magic -- The Magic3PiBall: 3 times pi is greater than 8.

Command Description
q Ask a question.
say Echo a message (may contain format switches).
choose Choose a random person from the channel by default or from a list if given
speak Set the spoken language.
expect Set the expected language.
new Add a new question, match or response for a given language.
delete Remove a question or response for a given language.
learn Add a new language.
example Show an example question or response for a given language.
contexts List the known question/answer/match/matchresponse contexts in a given language.
matches List the known match items for a given language.
total Count the number of items for a given language+category+context.
using Report what languages the bot is using on which channels.
languages Report the names of the known languages.
filters Report the names of the known text filters.
formats Describe the format switches.
unlearn Remove a language. (Manager access required.)
delcontext Delete a question/answer/match/matchresponse context for a given language. (Manager access required.)
newfilter Add a new text filter. (Manager access required.)
delfilter Delete a text filter. (Manager access required.)
threshold Set one of the (two) global random value thresholds. (Manager access required.)
qprefix Set the question prefix. (Manager access required.)
use Set both the expected language and the spoken language (no filter).
core Write the entire MagicTree to log. (Manager access requied.)
log

acro -- look up acronyms

Command Description
(call) look up an acronym
set set (or forget) an acronym definition

whereis -- find the geographical location of a TLD

Command Description
(call) locate a TLD or other fun stuff
add add a match to the lookup table
list list cached locations
remove remove cached location

rand -- spew random (and occasionally humorous) stuff

Command Description
zippy quotes from "zippy the pinhead"
pokey pokey is just weird
quote get or set a quote
addquote add a new quote for <nick>
delquote remove a quote
quotestats get stats about available quotes
rtopic put a random quote in the topic periodically (if not locked)

google -- do google searching

Command Description
(call) (shortcut for search)
count
search do a google search
spell get a spelling suggestion

slashdot -- get notified about slashdot stories

Command Description
stop stop notification of new entries
list list recipients of notification
interval set or get interval to poll slashdot
last print the last N slashdot titles (default N=1)
notify request notification of new articles (to channel or privately)

units -- Convert between standard and english measurements

Command Description
convert Convert between english and standard units
conv This is an alias to "convert"

bugzilla -- Show a link to a bug report with a brief description

Command Description
delzilla Delete a bugzilla from the list of define bugzillae.
bug Look up a bug number in a bugzilla.
listzilla List defined bugzillae.
addzilla Add a bugzilla to the list of defined bugzillae.

log -- logging of irc communication

Command Description
setlog set a log object's properties
newlog create a new irc logging object
getlog get a log object's properties
dellog delete a log object
logdir default directory for logs

messaging -- messages, ping notification and user tracking

Command Description
seen ask if the bot has seen another user
message leave a message for someone by nick
umessage leave a message for someone by userid
messages retrieve your messages
ping_notify ask for notification of pings
seen_length number of days to remember having "seen" someone
notify_interval number of hours to wait between message notification

Module Details

base -- base bot functions

These functions are for basic bot operations.

Commands

about give basic bot information
cperm (none)
usage about
help get help on something
cperm (none)
usage help <thing>
<thing> can be any one of "modules", "<module>", "<module> <command group>", "[<module>.]<command>", or "<module>.<setting>".
phelp print help to a channel (publicly)
cperm (none)
usage phelp <thing>
<thing> can be any one of "modules", "<module>", "<module> <command group>", "[<module>.]<command>", or "<module>.<setting>".
perm find required perms for a command
cperm (none)
usage perm <command>
path view or set the path
cperm ['or', 'manager', ':sargs == ""']
usage path [newpath]
which find where a command lives
cperm (none)
usage which <command>
This is usually used to find which module a command resides in.
get get a module setting
cperm (none)
usage get <modulename>[.<settingname>]
if <.settingname> is omitted, all module settings will be listed
set set a module setting
cperm (none)
usage set <modulename.settingname> <new value>
load load a bot module
cperm 'load'
usage load <module>
unload unload a bot module
cperm 'load'
usage unload <module>
RELOAD reload a core module
cperm 'load'
usage reload <module>
reload reload a bot module
cperm 'load'
usage reload <module>
die tell the bot to exit
cperm 'manager'
usage die
reconnect tell the bot to reconnect
cperm 'manager'
usage reconnect
restart tell the bot to restart fully
cperm 'manager'
usage restart

auth -- user and authentication management

The auth module contains commands for managing users, authentication,
and authorization.

USERS AND AUTHENTICATION

Users "accounts" are created and deleted with the 'meet' and
'forget' commands respectively.  The bot can be told to recognize a
nick as a known user with the 'recognize' command, which can also be
though of as something like the unix 'su' command.

There are three ways a nick can be authenticated as a known user:
1) by mask - if the user's profile contains a mask that matches
the current nickmask, they will be automatically authenticated
2) by password - passwords are managed with 'setpass' and 'authpass'
3) via the 'recognize' command

AUTHORIZATION

User permissions control what a user can and cannot do.  You can see
what permissions a user has with the 'profile' command, and what
'command permissions' (or cperm) are required by a command with the
'perm' command.  For example:

 kibot: perm recognize
 recognize requires: 'introduce'

Permissions can be added and removed with the 'give' and 'take'
commands.

PERMISSIONS TREES

There are two "trees" of permission: the implies tree and the grants
tree.  Each is a tree in the sense that one permission leads to
other permissions, which may in turn lead to others.  If one
permission is implied by another, it means the having the former
means you automatically have the latter.

 kibot: implies
 owner -> ['manager']
 manager -> ['op', 'introduce', 'load', 'kick', 'invite']

If a user has the 'manager' perm, then they automatically have the
'op' perm.

The grants tree controls what perms you can give to other people (or
yourself) given the perms that you have.

 kibot: grants
 owner -> ['manager', 'owner']
 manager -> ['op', 'introduce', 'kick', 'ignore', 'invite']

If a user has 'manager', they can give other people 'op', but they
cannot give other people 'manager'.

SPECIAL USERS

There are two special users: 'default' and 'unknown'.  The
permissions possessed by the 'default' user will be given to newly
created (via 'meet') users unless otherwise specified with the
options to 'meet'.  The permissions possessed by the 'unknown' user
are applied to anyone who is not recognized by the bot.  These users
can be managed with the standard commands: 'profile', 'give', and
'take'.

Commands

profile print a user's profile
cperm (none)
usage auth.profile [userid(s)]
give grant a user permissions
cperm (none)
usage auth.give <userid> <perm> [more perms]
take revoke a user's permissions
cperm (none)
usage auth.take <userid> <perm> [more perms]
authpass authenticate via password
cperm (none)
usage auth.authpass <userid> <password>
setpass set your password
cperm (none)
usage auth.setpass <new password>
addmask add a mask to a user's profile
cperm 'introduce'
usage auth.addmask <userid> <mask>
delmask delete mask from a user's profile
cperm 'introduce'
usage auth.delmask <userid> <mask>
mask can either be the mask itself, or the mask index (number)
meet introduce a user to me
cperm 'introduce'
usage auth.meet <nick> [userid [mask]] [with [only] perms]
if <mask> is the special string "nomask", no mask will be set
perms can be automatically granted using "with". If "with only" is
used, the default perms with not be granted.
recognize recognize someone as a known user
cperm 'introduce'
usage auth.recognize <nick> [userid [mask]]
if <mask> is the special string "nomask", no mask will be added
unrecognize UN-recognize someone
cperm 'introduce'
usage auth.unrecognize <nick>
forget forget a known user
cperm 'introduce'
usage auth.forget <userid>
users list known users
cperm 'manager'
usage auth.users
whois print a user's userid by nick
cperm 'manager'
usage auth.whois [nick(s)]
grants list perms that a user with <perm> can grant
cperm (none)
usage grants [<perm>s]
addgrant add <perms> that can be granted by a user with <PERM>
cperm 'owner'
usage addgrant <PERM> <perms>
delgrant remove <perms> that can be granted by a user with <PERM>
cperm 'owner'
usage delgrant <PERM> <perms>
implies list perms that are implied by <perm>
cperm (none)
usage implies [<perm>s]
addimply add <perms> that are implied by <PERM>
cperm 'owner'
usage addimply <PERM> <perms>
delimply remove <perms> that are implied by <PERM>
cperm 'owner'
usage delimply <PERM> <perms>

irc -- basic irc operations and channel management

Commands

op give ops to someone
cperm ('op' for target channel)
usage irc.op [channel] [nick(s)]
kick kick a user from a channel
cperm 'kick'
usage irc.kick [channel] nick(s) [comment]
invite invite a user to an invite-only channel
cperm ('invite' for target channel)
usage irc.invite [channel] [nick(s)]
channels list channels
cperm (none)
usage irc.channels
join tell the bot to join a channel
cperm 'manager'
usage irc.join <channel>
nick tell the bot to change nicks
cperm 'manager'
usage irc.nick <newnick>
part tell the bot to leave a channel
cperm 'manager'
usage irc.part [channel]
oper tell the bot to become an IRCop
cperm 'manager'
usage oper <operator class> <password>
mode execute a raw MODE command
cperm 'manager'
usage mode [target] <modes> [mode args]
raw send raw text to the irc server
cperm 'manager'
usage raw <text>

magic -- The Magic3PiBall: 3 times pi is greater than 8.

Commands

q Ask a question.
cperm (none)
usage q <question>
say Echo a message (may contain format switches).
cperm (none)
usage say <text>
choose Choose a random person from the channel by default or from a list if given
cperm (none)
usage choose [<list>]
speak Set the spoken language.
cperm (none)
usage speak <language[+filter]>
expect Set the expected language.
cperm (none)
usage expect <language>
new Add a new question, match or response for a given language.
cperm (none)
usage new <language> question|answer|special|match|matchresponse <context> <text>
delete Remove a question or response for a given language.
cperm (none)
usage delete <language> question|answer|special|match|matchresponse <context> <text>
learn Add a new language.
cperm (none)
usage learn <language>
example Show an example question or response for a given language.
cperm (none)
usage example <language> question|answer|special|match|matchresponse <context>
contexts List the known question/answer/match/matchresponse contexts in a given language.
cperm (none)
usage contexts <language> question|answer|special|match|matchresponse
matches List the known match items for a given language.
cperm (none)
usage matches <language> <context>
total Count the number of items for a given language+category+context.
cperm (none)
usage total <language> questions|answers|special|matches|matchresponses [<context>]
using Report what languages the bot is using on which channels.
cperm (none)
usage
languages Report the names of the known languages.
cperm (none)
usage
filters Report the names of the known text filters.
cperm (none)
usage
formats Describe the format switches.
cperm (none)
usage
unlearn Remove a language. (Manager access required.)
cperm 'manager'
usage unlearn <language>
delcontext Delete a question/answer/match/matchresponse context for a given language. (Manager access required.)
cperm 'manager'
usage delcontext <language> question|answer|match|response <context>
newfilter Add a new text filter. (Manager access required.)
cperm 'manager'
usage newfilter <name> <fullpath>
delfilter Delete a text filter. (Manager access required.)
cperm 'manager'
usage delfilter <name>
threshold Set one of the (two) global random value thresholds. (Manager access required.)
cperm 'manager'
usage threshold random|match <value in [0,1]>
qprefix Set the question prefix. (Manager access required.)
cperm 'manager'
usage qprefix <prefix>
use Set both the expected language and the spoken language (no filter).
cperm (none)
usage use <language>
core Write the entire MagicTree to log. (Manager access requied.)
cperm 'manager'
usage core
log
cperm (forbidden)
usage

acro -- look up acronyms

Commands

(call) look up an acronym
cperm (none)
usage acro <acronym>
set set (or forget) an acronym definition
cperm (none)
usage set <acronym> [definition]

whereis -- find the geographical location of a TLD

Commands

(call) locate a TLD or other fun stuff
cperm (none)
usage whereis <thing>
add add a match to the lookup table
cperm 'manager'
usage add <regex> <location>
If <location> includes a "%s", it will be replaced with the query
list list cached locations
cperm 'manager'
usage list
remove remove cached location
cperm (forbidden)
usage remove <i>
Remove the item with index <i>

rand -- spew random (and occasionally humorous) stuff

Commands

zippy quotes from "zippy the pinhead"
cperm (none)
usage
pokey pokey is just weird
cperm (none)
usage
quote get or set a quote
cperm (none)
usage quote [nick [new quote]]
if text appears after "nick", then it will be added as a new quote
addquote add a new quote for <nick>
cperm (none)
usage addquote <nick> <quote>
ex: addquote joe I really like it here
ex: addquote <jeff> yeah, me too
ex: addquote * jack wishes he were elsewhere
delquote remove a quote
cperm (none)
usage delquote <nick> <quote>
quotestats get stats about available quotes
cperm (none)
usage quotestats [nick]
rtopic put a random quote in the topic periodically (if not locked)
cperm ('op' for target channel)
usage rtopic [channel] <numhours> ["<format>"]
ex: rtopic #foo 4 "The best of #foo: %s"
Set <numhours> to 0 to stop.

google -- do google searching

Commands

(call) (shortcut for search)
cperm (none)
usage
count
cperm (none)
usage
search do a google search
cperm (none)
usage search [num_results] search term(s)
spell get a spelling suggestion
cperm (none)
usage spell <word>

slashdot -- get notified about slashdot stories

Commands

stop stop notification of new entries
cperm ['or', 'op', ':channel is None']
usage stop
list list recipients of notification
cperm 'manager'
usage
interval set or get interval to poll slashdot
cperm 'manager'
usage interval [seconds]
last print the last N slashdot titles (default N=1)
cperm ['or', 'op', ':channel is None']
usage last [N]
notify request notification of new articles (to channel or privately)
cperm ['or', 'op', ':channel is None']
usage notify

units -- Convert between standard and english measurements

Commands

convert Convert between english and standard units
cperm (none)
usage
conv This is an alias to "convert"
cperm (none)
usage

bugzilla -- Show a link to a bug report with a brief description

Commands

delzilla Delete a bugzilla from the list of define bugzillae.
cperm 'manager'
usage Format: delzilla shorthand
E.g.: delzilla rh
bug Look up a bug number in a bugzilla.
cperm (none)
usage Format: bug shorthand number
E.g.: bug rh 10301
listzilla List defined bugzillae.
cperm (none)
usage Format: listzilla [shorthand]
E.g.: listzilla rh; or just listzilla
addzilla Add a bugzilla to the list of defined bugzillae.
cperm 'op'
usage Format: addzilla shorthand url description
E.g.: addzilla rh http://bugzilla.redhat.com/bugzilla Red Hat Zilla

log -- logging of irc communication

The default logfile directory is stored in the setting 'logdir'.  It
can be viewed with 'get log.logdir' and set with 'set log.logdir NEWDIR'
This module maintains logs of irc communication that the bot sees.  This
includes channel conversation, private messages, and server notices.  All
logging is facilitated via 'logging objects'.  Each object has a 'type',
which determines the format of its output (xml, text, etc), a filename,
list of channels to log, list of nicks whose private communication (with the
bot) to log, and list of servers whose notices to log.

Here are some notes on these:

type
there are currently two builtin types, 'xml' and 'text'.  This is
currently no facility for using 'plugin' types, although it's easy
enough to add on to the 'official' module and then put it in a
local modules directory.  If there's demand, a plugin machanism
can be added.

filename
this is a string which can contain strftime formats.  This value
will be joined with the 'logdir' setting to get the filename to
which logs should be written.  Therefore, if the filename begins
with a '/', it will be interpreted as an absolute filename.  This
way, you can specify a logdir where most logs go, but still
specify an absolute path for others.  Logging objects
automatically log to the right place when logdir or filenames are
changed, although old logs are never moved.

channels
this is a (comma-separated) list of channels to log.  The list can
contain glob characters, so you could do '#dhg,#kibot*'

nicks
this is a (comma-separated) list of nicks whose private
communication with the bot should be logged.  This includes only
private communication going in either direction between the given
nick(s) and the bot.  It DOES NOT (in fact, CAN not) log private
communication between two users.

servers
this is a (comma-separated) list of servers whose notices should
be logged.  Because kibot currently only supports single-server
connections, you should really either set this to '*' if want
notices, or '' if you don't.

Commands

setlog set a log object's properties
cperm 'manager'
usage setlog <label> <property name> <new value>
legal property names: filename channels nicks servers
type cannot be set dynamically - you must destroy and recreate the object
newlog create a new irc logging object
cperm 'manager'
usage newlog <label> <filename> <type> [<channels> [<nicks> [<servers>]]]
<filename> will be treated as an strftime format
<type> should be one of: xml text
<channels>, <nicks> and <servers> are comma-separated lists which can contain globs. Empty quotes can be used to indicate an empty list.
ex: newlogger private private-%Y%m%d.xml xml '' * *
This will log all private communication and server notices.
getlog get a log object's properties
cperm 'manager'
usage getlog [label(s)]
dellog delete a log object
cperm 'manager'
usage dellog [label(s)]

Settings

logdir default directory for logs
default None
get cperm (none)
set cperm 'manager'

messaging -- messages, ping notification and user tracking

Commands

seen ask if the bot has seen another user
cperm (none)
usage seen <userid/nick> [more userids/nicks]
message leave a message for someone by nick
cperm (none)
usage message <nick> <message>
umessage leave a message for someone by userid
cperm (none)
usage message <userid> <message>
messages retrieve your messages
cperm (none)
usage messages
ping_notify ask for notification of pings
cperm (none)
usage ping_notify [on|off]

Settings

seen_length number of days to remember having "seen" someone
default 30
get cperm (none)
set cperm 'manager'
notify_interval number of hours to wait between message notification
default 12
get cperm (none)
set cperm 'manager'