astrae

Guides

Commands

Prefix, slash, hybrid, user/message menus. A decorator registers the callback. Slash metadata syncs when the client is ready. Prefix reads gateway messages, so guild use needs Message Content. Slash does not.

from astrae import Author, CommandContext, CurrentGuild, CurrentRole

@bot.hybrid_command(name="who", description="Show invocation context")
async def who(
    ctx: CommandContext, author: Author, guild: CurrentGuild, role: CurrentRole
) -> None:
    await ctx.reply(
        f"{author.username} in {guild.id if guild else 'DM'}"
        + (f" as {role.mention}" if role else "")
    )

Catalog, exports.

Registration

Name Purpose
command Prefix command that can also sync as an application command.
prefix_command Prefix only.
slash_command Chat-input application command.
hybrid_command One callback for prefix and slash.
context_menu User or message context-menu command.
sync_commands=False Skip Discord overwrite; another step owns registration.

Injected values

Not options. They come from the invoke. Guild ones are None in a DM.

Name Purpose
First argument Always the context.
CommandContext Interaction invoke: reply, defer, followup, update.
PrefixContext Prefix invoke: channel replies and the same styled helpers.
Author / CurrentUser Invoking user.
CurrentMember Invoking member in a guild.
CurrentGuild Guild for this invoke.
CurrentChannel Channel for this invoke.
CurrentRole Invoking member's highest role.
StringOption … AttachmentOption Slash options on Annotated.

Replies and prompts

Name Purpose
ctx.success / ctx.approve Approve-style mention embed.
ctx.error / ctx.deny Error-style mention embed.
ctx.neutral Neutral mention embed.
ContextTheme Colors and emojis. Explicit Client(context_theme=...) wins.
ASTRAE_COLOR_APPROVED Green. Also _WARNED, _DENIED, _NEUTRAL. #RRGGBB, hex, or a named color.
ctx.prompt / ctx.confirm Approve / Decline buttons. Decline or timeout raises UserInputError.
ctx.check Adds a 👍 reaction.
ctx.paginate Button paginator for strings, embeds, fields, or files. Invoker only. 60s timeout.
ctx.paginator Build the Paginator view without sending.
ctx.files Paginate uploads.
ASTRAE_PAGINATOR_PREVIOUS Override ◀️. Also _NEXT, _NAVIGATE, _CANCEL. Unicode or <:name:id>.

Errors, middleware, extensions

Name Purpose
Middleware Wrap every invoke: checks, timing, app context. Call the next stage once.
guild_only Reject DMs.
owner_only Allow configured owner IDs only. Does not read Client.owners unless you pass them.
Cog.cog_check Gate every command in the cog. False → silent CheckFailure.
CommandError Expected rejection. Library maps most to ctx.error, help, or a cooldown reaction.
@client.command_error Replace the default mapping. Also cog_command_error and @command.error.
Unexpected exceptions Logged. Optional Sentry / Tracelet. User sees the error text, not a traceback.
setup_posthog() command_used after success or failure.
Extension setup(client) Register commands, listeners, cogs. Sync or async. Must be safe to repeat.
Reload Tears down the old extension, reloads imported submodules, runs setup again.