Custom Commands & Aliases
Relevant source files
The following files were used as context for generating this wiki page:
The Custom Commands and Aliases modules allow users to extend the bot's functionality by creating user-defined triggers. Custom Commands store and display text responses, while Aliases create alternative names or shortcuts for existing bot commands. These systems enable server-specific personalization and improved command accessibility without requiring modifications to the core codebase.
Sources: redbot/cogs/customcom/customcom.py:165-171, redbot/cogs/alias/alias.py:38-44
Custom Commands Architecture
The CustomCommands cog manages the creation, execution, and storage of user-defined text responses. It uses a CommandObj helper class to handle internal logic and data persistence via the Config framework. Custom commands are stored per guild and support both static and randomized responses.
Data Model and Storage
Custom commands are stored as dictionary objects containing metadata about the creator and the response content.
| Field | Type | Description |
|---|---|---|
author | dict | Contains the id and name of the creator. |
command | str | The trigger word (lowercase only). |
response | str or list | The text to return; multiple entries enable randomization. |
cooldowns | dict | Mapping of cooldown scopes (guild, member, channel) to seconds. |
created_at | str | Timestamp of creation. |
editors | list | List of user IDs who modified the command. |
Sources: redbot/cogs/customcom/customcom.py:112-120, redbot/cogs/customcom/customcom.py:180-181
Execution Logic
Custom commands use the on_message_without_command listener to intercept messages that match a defined trigger but are not registered as standard bot commands.
Argument Parsing
Custom commands support dynamic parameters using curly-brace syntax (e.g., {0}, {author}). The prepare_args function converts these into Parameter objects, allowing the bot to parse user input as if it were a native command.
- Positional Arguments:
{0},{1}... up to{9}. - Context Variables:
{author},{channel},{guild},{message}. - Type Hinting:
{0:int},{1:str}supports basic type conversion.
Sources: redbot/cogs/customcom/customcom.py:516-583, redbot/cogs/customcom/customcom.py:608-620
Alias System
The Alias cog provides a shortcut mechanism where one command name maps to another command string, including optional arguments. Aliases can be defined at the global level (bot-wide) or the server level.
Alias Resolution Flow
When a message is received, the Alias cog attempts to translate the content before the bot processes commands.
Key Alias Features
- Global Aliases: Only configurable by bot owners; available in all guilds.
- Server Aliases: Configurable by administrators; local to the specific guild.
- Argument Appending: Any arguments provided after the alias trigger are automatically appended to the resulting command execution.
- Validation: Aliases cannot overwrite existing bot commands or reserved names.
Sources: redbot/cogs/alias/alias.py:43-47, redbot/cogs/alias/alias.py:168-175, redbot/cogs/alias/alias.py:181-190
Management and Configuration
Both systems provide administrative tools for listing, searching, and modifying entries.
Comparison Table
| Feature | Custom Commands (CC) | Aliases |
|---|---|---|
| Primary Purpose | Display stored text/info | Create shortcuts for existing commands |
| Response Type | Text/Embed (static or random) | Triggering another command |
| Scope | Server-only | Server and Global |
| Parameters | Supports internal placeholders | Appends extra arguments to base command |
| Permissions | Managed by Mod/Admin | Managed by Admin/Owner |
Sources: redbot/cogs/customcom/customcom.py:173-176, redbot/cogs/alias/alias.py:38-42
Search and Metadata
The Custom Commands system implements fuzzy searching via rapidfuzz to help users find triggers by name or content preview. The help system also integrates these triggers, with RedHelpFormatter showing aliases if show_aliases is enabled in HelpSettings.
Sources: redbot/cogs/customcom/customcom.py:228-243, redbot/core/commands/help.py:255-260
Conclusion
The Custom Commands and Aliases systems are essential for bot extensibility. Custom Commands provide a flexible way to manage informational responses with dynamic placeholders, while Aliases streamline user experience by providing shorthand access to complex command structures. Both leverage the core Config and listener architectures to ensure reliable performance across diverse server environments.