Commands

The main purpose of sibyl is to do cool and useful things in a chat room. Basic help is avaiable with sibyl help.

Running Commands

In order to run a command, you have to send sibyl a message starting with a valid command name. If you are in a private chat, you can simply do help. However, if you are in a chat room, you need to start the command with sibyl's nick name in that chat room. For example sibyl help. If you set cmd_prefix = ! in the config file, you can do !help in a chat room.

When you run a command, you can put additional text after the command name. This additional text will be passed to the command, and we will refer to it as "parameters" or "arguments". For example, to get help for the errors command, we would call sibyl help errors. The help command then receives errors as an argument, and will only display information about the errors command.

Sibyl uses spaces as the argument separator, so some commands accept multiple arguments, e.g. sibyl bookmark set nightvale. Here, the first parameter is set and the second parameter is nightvale. Because of this, if you ever need to pass an argument that has spaces in it, for example a file name, you can surround it with double quotes. For example, sibyl audio "A Song.mp3". If you just do sibyl audio A Song.mp3 it won't work right, because instead of seeing the entire file name as a single argument, sibyl will see A as the first parameter and Song.mp3 as the second parameter.

Sample commands broken down into parts:

sibyl help errors
 - sibyl = nick name
 - help = command
 - errors = first parameter

!play A Song.mp3
 - ! = cmd_prefix (if set in config file)
 - play = command
 - A = first paramter
 - Song.mp3 = second parameter

!play "A Song.mp3"
 - ! = cmd_prefix (if set in config file)
 - play = command
 - A Song.mp3 = first parameter

One quick caveat on that though, certain functions that only take one argument ignore spaces and quotes entirely, for example all, echo, and say, which just reproduce their input, verbatim, to a specific target.

Finally, you can redo your last command. You can do so by calling the redo command. If you have cmd_prefix set, you can also redo your last command by sending it twice, e.g. !! is the same as sibyl redo.

Controlling Access

You can get fine-grained control of who can execute which commands using sibyl's Black/White list. This is set in the config file with the bw_list option. Note that if you don't set bw_list, the default behavior is to allow any user to execute any command, except in the case explained below.

Certain commands are dangerous if misused, and so are completely disabled by default. You can enable them by settting chat_ctrl = True in your config file. This restriction is completely separate from and overrides bw_list. If you choose to enable them, you should really consider restricting them with bw_list so only you or trusted users and run them.

Getting Help

You can use the help command to get a list of all chat commands and brief descriptions, or you can use help [name] to get help for a specific command. For details on the formatting of help entries see its section.

Plug-Ins

Most commands in Sibyl exist as plug-in scripts. For info about individual commands, refer to the pages below:

• Bookmark - keep track of where you are in TV shows or podcasts
• General - miscellaneous useful commands
• Library - search and play files from local or samba sources
• Note - create notes about anything
• Room - join/leave rooms and other commands
• XBMC - control an XBMC/Kodi/OSMC instance

Adding New Plug-Ins

All you have to do is copy the plug-in .py file to your command directory. If you don't know where that is, find where you downloaded sibyl and it will be called cmds. If you're planning to do any work with sibyl and git, consider placing the files in cmds/custom. If you have it enabled, you can use the reboot chat command to load the new plug-ins. Otherwise you'll have to restart Sibyl to use them.

Disabling Plug-Ins

This is done using the config file in one of two ways. First, you can use the disable config option to specify plug-ins you don't want Sibyl to load. For example:

disable = bookmark,library,xbmc

You can also use the enable config option to specify which to plug-in you want loaded. If you only have the 6 built-in plug-ins, then the below is equivalent to above:

enable = general,note,room

If you use both disable and enable at the same time, they will both take effect, meaning a plug-in will only be loaded if it is in enable and not in disable.

Commands

• about: list version and loaded plugins
• errors: list errors, for example those encountered during bot startup
• git: return a link to the github page
• hello: reply if someone says hello
• help: respond with help info - help [command]
• last: respond with the text of the last command that was executed
• redo: execute the last command again
• stats: respond with some usage statistics
• uptime: respond with how long the bot has been alive

---

about

sibyl about

Respond with version and loaded plug-in info.

---

errors

sibyl errors [*] [minlvl=warning] [search1=-startup search2]

List errors deserving user attention. When called without arguments, it doesn't show startup errors. Some example calls:

• sibyl errors * - show all errors
• sibyl errors critical - only show critical errors
• sibyl errors config - show errors that contain the string config

Valid minlvl options: debug, info, warning, error, critical

---

git

sibyl git

Returns a link to the github project page.

---

hello

sibyl hello

Simple test to make sure the bot is working. Sibyl responds with Hello World!.

---

help

sibyl help [command]

If no arguments are passed, print short help text for every command. Otherwise print the help text only for command. Formatting notes:

• Optional arguments are listed inside []
• If there are a set number of choices, they appear as (one|two|three...)
• When looking at an individual command, the plugin providing it appears in front as [plugin]
• To show plugin names when listing all commands set help_plugin = True in your config

---

last

sibyl last

Respond with the last command the user executed.

---

redo

sibyl redo

Execute the last command again (i.e. the most recent command that was not redo). Can be called multiple times in succession. Every user's last command is tracked separately.

---

stats

sibyl stats

Responds with some usage statistics; explanations for each follow.

• Born - when the bot last started or rebooted
• Cmds-Run - number of commands successfully run
• Cmds-Forbid - number of times a user tried to run a command forbidden by bw_list
• Cmds-Error - number of times a command that raised an exception and failed
• Disconnects - number of times a protocol has disconnected

---

uptime

sibyl uptime

Responds with the amount of time the bot has been running (since last start or reboot). Format is:

Up for [days] days and [hours]:[minutes]:[seconds]