API reference
Commands API catalog
More than the command guide. Decorator signatures
differ by kind — check the type hints you actually installed.
Registration
| Name |
Purpose |
Client.command |
Prefix invoke; may also sync as an application command. |
Client.prefix_command |
Prefix only. |
Client.slash_command |
Chat-input application command. |
Client.hybrid_command |
Prefix and slash, one callback. |
Client.context_menu |
User- or message-target context menu. |
| Module-level decorators |
Same names, then attach to a client, cog, or plugin. |
| Metadata |
Name, description, guild scope, NSFW, default member permissions, localizations, contexts, aliases, auto_defer. |
| Sync |
Global commands are bulk-overwritten. Do not compete with another deploy. |
Options and conversion
| Name |
Purpose |
Annotated[T, Option(...)] |
Discord-visible option. |
StringOption … AttachmentOption |
Description, required/default, choices, bounds, channel types, localizations. |
| Enum annotations |
Become choices when the Python type is supported. |
| Optional / default |
Affect requiredness. Discord caps option counts and lengths. |
| Prefix conversion |
Quoted tokens, positionals, flags, mentions/IDs, attachments. |
BadArgument / ConversionError |
Conversion failed. |
MissingRequiredArgument |
Value omitted. |
Author / CurrentUser / CurrentMember / CurrentGuild / CurrentChannel / CurrentRole |
Injected. Not options. Guild ones can be None in a DM. |
Groups, middleware, errors
| Name |
Purpose |
AppCommand.subcommand |
Nested command. |
| Prefix grouping |
group, flat, omit, aliases, nested groups. |
AppCommand.error |
Command-specific handler. |
Client.add_middleware / @client.middleware |
Wrap invoke. Call the next stage once if the callback should run. |
guild_only |
Reject DMs. |
owner_only |
Configured owner IDs. Not Discord permission config. |
CommandError |
Expected failure. |
CommandInvokeError |
Callback raised; original exception attached. |
| Default handler |
Missing args, converters, cooldowns, permissions, NSFW, flags, invoke errors → ctx.error / help. |
| Silent |
NotOwner and a bare CheckFailure. |
Cogs, plugins, extensions
| Name |
Purpose |
Cog |
Decorated commands/listeners. Optional setup / teardown. |
cog_check |
Gate every command in the cog. False → silent CheckFailure. May be async. |
cog_command_error |
After per-command handler, before client handler. |
Plugin |
Lightweight command/listener bundle. |
setup(client) |
Extension entry. Sync or async. Recorded for later removal. |
| Reload |
Repeat setup. Make it idempotent. Close resources in teardown. |
@listener |
Event callback for cog discovery. |
add_listener / add_cog / add_plugin |
Dynamic registration. |
Interaction utilities
| Name |
Purpose |
View |
Buttons/selects with callbacks. |
button |
Bind a view method. |
View.rows() |
Serialize components. |
Paginator |
ctx.paginate(pages) sends it. ctx.paginator(pages) builds it. |
| Pages |
Strings, embeds, field dicts, or Upload files. Invoker-only. Wrap, jump, time out. |
| Paginator emojis |
emojis=, ASTRAE_PAGINATOR_*, or .env / ASTRAE_ENV_FILE. |
Modal |
Modal inputs and submit. |
ComponentCollector |
Wait for a custom ID. Redis can span workers. |
InteractionApp |
HTTP endpoint. verify uses the application public key. |
| Restarts |
Callbacks are not persisted. Re-register persistent views. |
Context
| Name |
Purpose |
client / bot |
Owning client. |
user / member / author |
Invoker. |
guild_id / channel_id / guild / channel / role / me |
Invoke location. role is highest guild role. |
created_at / theme / replied_message |
Timestamp, ContextTheme, last reply. |
success / approve / error / deny / neutral |
{emoji} {mention}: {text} embeds. |
ASTRAE_COLOR_* |
Theme colors from env / .env / ASTRAE_ENV_FILE. |
prompt / confirm |
Approve / Decline buttons. |
check |
👍 reaction. |
embed / create |
Build embed payloads. |
files |
Paginate uploads. |
get_attachment |
Invoking message, then reply, then recent history. |
suppress_embeds / quietly_delete |
Edit or delete without raising. |
is_dangerous / valid_permissions |
Elevated role checks. |
paginate / paginator |
Send or build a Paginator. |
hydrate() |
get_guild() / get_channel(). May hit REST. Do not hydrate every invoke. |
CommandContext
| Name |
Purpose |
interaction / message / command_name |
Source payload. |
defer |
Acknowledge a slow interaction. |
reply |
Initial response, or edit after defer/reply. |
followup |
Another message. Returns Message. |
update |
Edit the component's source message. |
defer_update |
Acknowledge a component without a new message. |
send_modal |
Open a modal. |
delete / fetch / edit |
Original response. |
autocomplete |
Autocomplete choices. |
Interaction tokens are short-lived secrets. Discord is the authority if the
token expires.
PrefixContext
| Name |
Purpose |
| Prefix / message |
Invocation source. |
| Replies |
Ordinary channel messages. Not ephemeral. |
AllowedMentions |
Client default on both context types. Override per response only when intended. |