xK/xB.adoc

xB(1)

Name

xB - modular IRC bot

Synopsis

xB [OPTION]…​

Description

xB is a modular IRC bot with a programming language-agnostic plugin architecture based on co-processes.

Options

-d, --debug

Print more information to help debug various issues.

-h, --help

Display a help message and exit.

-V, --version

Output version information and exit.

--write-default-cfg[=PATH]

Write a configuration file with defaults, show its path and exit.

The file will be appropriately commented.

Commands

The bot accepts the following commands when they either appear quoted by the prefix string on a channel or unquoted as a private message sent directly to the bot, on the condition that the sending user matches the admin regular expression or that it is left unset:

quote [message]

Forwards the message to the IRC server as-is.

quit [reason]

Quits the IRC server, with an optional reason string.

status

Sends back a report about its state and all loaded plugins.

load plugin[, plugin]…​

Tries to load the given plugins.

unload plugin[, plugin]…​

Tries to unload the given plugins.

reload plugin[, plugin]…​

The same as unload immediately followed by load.

Plugins

Plugins communicate with the bot over their standard input and output streams using the IRC protocol. (Caveat: the standard C library doesn’t automatically flush FILE streams for pipes on newlines.) A special XB command is introduced for RPC, with the following subcommands:

XB get_config key

Request the value of the given configuration option. If no such option exists, the value will be empty. The response will be delivered in the following format:

XB :value

This is particularly useful for retrieving the prefix string.

XB print message

Make the bot print the message on its standard output.

XB register

Once a plugin issues this command, it will start receiving all of the bot’s incoming IRC traffic, which includes data from the initialization period.

All other commands will be forwarded directly to the IRC server.

Files

xB follows the XDG Base Directory Specification.

~/.config/xB/xB.conf

The bot’s configuration file. Use the --write-default-cfg option to create a new one for editing.

~/.local/share/xB/

The initial working directory for plugins, in which they may create private databases or other files as needed.

~/.local/share/xB/plugins/

/usr/local/share/xB/plugins/

/usr/share/xB/plugins/

Plugins are searched for in these directories, in order, unless the plugin_dir configuration option overrides this.

Reporting bugs

Use https://git.janouch.name/p/xK to report bugs, request features, or submit pull requests.