Commands Package

This package acts almost identically to discord.ext.commands; i.e. all of the attributes from’s are also in ours. Some of these attributes, however, have been slightly modified, while others have been added to extend functionlities used throughout the bot, as outlined below.

redbot.core.commands.command(name=None, cls=<class 'redbot.core.commands.commands.Command'>, **attrs)[source]

A decorator which transforms an async function into a Command.

Same interface as discord.ext.commands.command., **attrs)[source]

A decorator which transforms an async function into a Group.

Same interface as

class redbot.core.commands.Command(*args, **kwargs)[source]

Command class for Red.

This should not be created directly, and instead via the decorator.

This class inherits from discord.ext.commands.Command. The attributes listed below are simply additions to the ones listed with that class.


A list of check predicates which cannot be overridden, unlike Requires.checks.

Type:List[coroutine function]

A translator for this command’s help docstring.

allow_for(model_id: Union[int, str], guild_id: int) → None[source]

Actively allow this command for the given model.

  • model_id (Union[int, str]) – Must be an int if supplying an ID. str is only valid for “default”.
  • guild_id (int) – The guild ID to allow this cog or command in. For global rules, use 0.
coroutine can_run(ctx: Context, *, check_all_parents: bool = False, change_permission_state: bool = False) → bool[source]

Check if this command can be run in the given context.

This function first checks if the command can be run using’s method discord.ext.commands.Command.can_run, then will return the result of Requires.verify.

Keyword Arguments:
  • check_all_parents (bool) – If True, this will check permissions for all of this command’s parents and its cog as well as the command itself. Defaults to False.
  • change_permission_state (bool) – Whether or not the permission state should be changed as a result of this call. For most cases this should be False. Defaults to False.
coroutine can_see(ctx: Context)[source]

Check if this command is visible in the given context.

In short, this will verify whether the user can run the command, and also whether the command is hidden or not.

Parameters:ctx (Context) – The invocation context to check with.
Returns:True if this command is visible in the given context.
Return type:bool
clear_rule_for(model_id: Union[int, str], guild_id: int) → Tuple[redbot.core.commands.requires.PermState, redbot.core.commands.requires.PermState][source]

Clear the rule which is currently set for this model.

  • model_id (Union[int, str]) – Must be an int if supplying an ID. str is only valid for “default”.
  • guild_id (int) – The guild ID. For global rules, use 0.
disable_in(guild: discord.guild.Guild) → bool[source]

Disable this command in the given guild.

Parameters:guild (discord.Guild) – The guild to disable the command in.
Returns:True if the command wasn’t already disabled.
Return type:bool
coroutine do_conversion(ctx: Context, converter, argument: str, param: inspect.Parameter)[source]

Convert an argument according to its type annotation.

Raises:ConversionFailure – If doing the conversion failed.
Returns:The converted argument.
Return type:Any
enable_in(guild: discord.guild.Guild) → bool[source]

Enable this command in the given guild.

Parameters:guild (discord.Guild) – The guild to enable the command in.
Returns:True if the command wasn’t already enabled.
Return type:bool

A decorator that registers a coroutine as a local error handler.

A local error handler is an on_command_error() event limited to a single command.

The on_command_error event is still dispatched for commands with a dedicated error handler.

Red’s global error handler will ignore commands with a registered error handler.

To have red handle specific errors with the default behavior, call Red.on_command_error with unhandled_by_cog set to True.

For example:

async def a_command_error_handler(self, ctx, error):

    if isisntance(error, MyErrrorType):
        await, error, unhandled_by_cog=True)
Parameters:coro (coroutine function) – The coroutine to register as the local error handler.
Raises:discord.ClientException – The coroutine is not actually a coroutine.

Help string for this command.

If the help kwarg was passed into the decorator, it will default to that. If not, it will attempt to translate the docstring of the command’s callback function.


Returns all parent commands of this command.

This is sorted by the length of qualified_name from highest to lowest. If the command has no parents, this will be an empty list.

class redbot.core.commands.Group(*args, **kwargs)[source]

Group command class for Red.

This class inherits from Command, with GroupMixin and discord.ext.commands.Group mixed in.

class redbot.core.commands.Context(**attrs)[source]

Command invocation context for Red.

All context passed into commands will be of this type.

This class inherits from discord.ext.commands.Context.


The command prefix, but a mention prefix is displayed nicer.

coroutine embed_colour()[source]

Helper function to get the colour for an embed.

Returns:The colour to be used
Return type:discord.Colour
coroutine embed_requested()[source]

Simple helper to call bot.embed_requested with logic around if embed permissions are available

Returns:True if an embed is requested
Return type:bool
coroutine maybe_send_embed(message: str) → discord.message.Message[source]

Simple helper to send a simple message to context without manually checking ctx.embed_requested This should only be used for simple messages.


message (str) – The string to send


the message which was sent

Return type:



The bot member or user object.

If the context is DM, this will be a discord.User object.
coroutine send(content=None, **kwargs)[source]

Sends a message to the destination with the content given.

This acts the same as discord.ext.commands.Context.send, with one added keyword argument as detailed below in Other Parameters.


content (str) – The content of the message to send.

Other Parameters:

The message that was sent.

Return type:


coroutine send_help(command=None)[source]

Send the command help message.

coroutine send_interactive(messages: Iterable[str], box_lang: str = None, timeout: int = 15) → List[discord.message.Message][source]

Send multiple messages interactively.

The user will be prompted for whether or not they would like to view the next message, one at a time. They will also be notified of how many messages are remaining on each prompt.

  • messages (iterable of str) – The messages to send.
  • box_lang (str) – If specified, each message will be contained within a codeblock of this language.
  • timeout (int) – How long the user has to respond to the prompt before it times out. After timing out, the bot deletes its prompt message.
coroutine tick() → bool[source]

Add a tick reaction to the command message.

Returns:True if adding the reaction succeeded.
Return type:bool


This module manages the logic of resolving command permissions and requirements. This includes rules which override those requirements, as well as custom checks which can be overriden, and some special checks like bot permissions checks.

class redbot.core.commands.requires.PrivilegeLevel[source]

Enumeration for special privileges.


User has the admin role.


User is a bot owner.


User is the guild level.

MOD = 2

User has the mod role.

NONE = 1

No special privilege level.

class redbot.core.commands.requires.PermState[source]

Enumeration for permission states used by rules.


This command has been actively allowed, default user checks should be ignored.


This command has been actively denied, terminate the command chain.


This command has been actively allowed by a permission hook. check validation doesn’t need this, but is useful to developers


This command has been actively denied, but there exists a subcommand in the ACTIVE_ALLOW state. This occurs when PASSIVE_ALLOW and ACTIVE_DENY are combined.


This command has been actively denied by a permission hook check validation doesn’t need this, but is useful to developers


No overrides have been set for this command, make determination from default user checks.


There exists a subcommand in the ACTIVE_ALLOW state, continue down the subcommand tree until we either find it or realise we’re on the wrong branch.

class redbot.core.commands.requires.Requires(privilege_level: Optional[redbot.core.commands.requires.PrivilegeLevel], user_perms: Union[Dict[str, bool], discord.permissions.Permissions, None], bot_perms: Union[Dict[str, bool], discord.permissions.Permissions], checks: List[Callable[[Context], Union[bool, None, Awaitable[Optional[bool]]]]])[source]

This class describes the requirements for executing a specific command.

The permissions described include both bot permissions and user permissions.


A list of checks which can be overridden by rules. Use Command.checks if you would like them to never be overridden.

Type:List[Callable[[Context], Union[bool, Awaitable[bool]]]]

The required privilege level (bot owner, admin, etc.) for users to execute the command. Can be None, in which case the user_perms will be used exclusively, otherwise, for levels other than bot owner, the user can still run the command if they have the required user_perms.


The required permissions for users to execute the command. Can be None, in which case the privilege_level will be used exclusively, otherwise, it will pass whether the user has the required privilege_level _or_ user_perms.


The required bot permissions for a command to be executed. This is not overrideable by other conditions.

DEFAULT = 'default'

The key for the default rule in a rules dict.


Should be used in place of a guild ID when setting/getting global rules.

clear_all_rules(guild_id: int) → None[source]

Clear all rules of a particular scope.

This will preserve the default rule, if set.

Parameters:guild_id (int) – The guild ID to clear rules for. If set to Requires.GLOBAL, this will clear all global rules and leave all guild rules untouched.
get_rule(model: Union[int, str, discord.user.User,,,, discord.role.Role, redbot.core.commands.converter.GuildConverter, discord.member.Member], guild_id: int) → redbot.core.commands.requires.PermState[source]

Get the rule for a particular model.

  • model (Union[int, str, PermissionModel]) – The model to get the rule for. str is only valid for Requires.DEFAULT.
  • guild_id (int) – The ID of the guild for the rule’s scope. Set to Requires.GLOBAL for a global rule.

The state for this rule. See the PermState class for an explanation.

Return type:


set_rule(model_id: Union[str, int], rule: redbot.core.commands.requires.PermState, guild_id: int) → None[source]

Set the rule for a particular model.

  • model_id (Union[str, int]) – The model to add a rule for. str is only valid for Requires.DEFAULT.
  • rule (PermState) – Which state this rule should be set as. See the PermState class for an explanation.
  • guild_id (int) – The ID of the guild for the rule’s scope. Set to Requires.GLOBAL for a global rule.
coroutine verify(ctx: Context) → bool[source]

Check if the given context passes the requirements.

This will check the bot permissions, overrides, user permissions and privilege level.


ctx ("Context") – The invkokation context to check with.


True if the context passes the requirements.

Return type:


  • BotMissingPermissions – If the bot is missing required permissions to run the command.
  • CommandError – Propogated from any permissions checks.