Configuration

All settings except secrets go in config.yaml, in the folder you run the bot from. It's loaded with ruamel.yaml and checked with pydantic. If something is the wrong type, the bot stops at startup with an error saying which field is wrong.

Secrets (TOKEN, MONGO_URI) go in .env instead: see Getting started.

Bot identity

Key	Type	Default	What it does
name	string	"ruby"	Internal name: used for the logger and as the MongoDB database name. Letters, numbers and underscores only.
friendly_name	string	"Ruby"	The name people see. Anything goes.
version	string	"v0.1.0"	Shown in the default status.
prefix	string	"r!"	Command prefix. See Prefix.
invite_link	string	"No invite link"	Your bot's invite link, for cogs that want to show it.
owners	list of IDs	[]	User IDs of the bot's owners. Used by commands.is_owner() and bot.is_owner().

Prefix

People can use the prefix as written or in capitals, with or without a space after it. With prefix: "r!", all of these work:

r!help    R!help    r! help    R! help    @Ruby help

Mentioning the bot always works as a prefix too.

Presence

Key	Type	Default	What it does
statuses	list of strings, or null	["<friendly_name> <version>"]	Custom statuses to rotate through, picked at random. null means no custom status.
status_interval	number	60	Seconds between status changes.
status	online / idle / dnd / invisible / offline	online	The coloured dot.

statuses:
  - "Watching the pond"
  - "r!help"
status_interval: 120
status: idle

TIP

Leaving statuses out and setting it to null are different. Left out, you get "Ruby v0.1.0". Set to null, you get no status at all.

Behaviour

Key	Type	Default	What it does
strings	map	{}	Rewords any message. See Strings.
log_level	level name or number	INFO	The lowest level that's logged, both to bot.log and to the log channel. E.g. "DEBUG", "WARNING".
embeds	bool	true	Whether success() and error() reply with coloured embeds (true) or plain ✅ | message text (false).

Cog settings

Key	Type	Default	What it does
currency.currency	string	"points"	The name of your server's currency, for cogs that use one.
cogs	map	{}	One section per cog, in whatever shape that cog wants. See Writing cogs.

currency:
  currency: "beans"

cogs:
  birthdays:
    channel: 123456789012345678
    role: 123456789012345678
  bump:
    channel: 123456789012345678

Server

Ruby is made for one server, and this describes it.

Key	Type	Default	What it does
server.id	ID	0	Your server's ID.
server.name	string	"Server"	Your server's name.
server.invite	string	"No invite link"	An invite to your server.
server.channels	map of name → ID	{}	Channel IDs for cogs to look up by name.

log is Ruby's own: set it to a channel ID to get log messages in Discord, or leave it out (or 0) for none. Add any other channels your cogs need:

server:
  id: 123456789012345678
  name: "Belugat's Safe Space"
  invite: "https://discord.gg/example"
  channels:
    log: 123456789012345678
    spam: 0
    honeypot: 123456789012345678

In a cog, read them with self.bot.server.channels["spam"].

Reloading

The config is read once, the first time anything asks for it, and then cached. To read it again without restarting (for example from an owner command):

from ruby.utils import get_config

self.bot.cfg = get_config(force=True)

Strings take effect straight away. A cog that copied its settings in __init__ (like the self.cfg pattern in Writing cogs) keeps the old ones until it's reloaded. Things set up at startup, such as the prefix, the database and the status loop, need a restart.