Commands

Defining commands

Use @bot.command() for inline definitions or @cog_command() inside a Cog:

from cordless import Cordless

bot = Cordless()

@bot.command("ping", description="Check latency")
async def ping(ctx):
    await ctx.send("Pong!")

Command names are validated at decoration time: 1–32 lowercase letters, digits, - or _.

With a Cog

from cordless import Cog, cog_command

class MyCog(Cog):
    @cog_command("hello", description="Say hello")
    async def hello(self, ctx):
        await ctx.send(f"Hello, {ctx.user['username']}!")

bot.add_cog(MyCog())

Options

Declare options as typed parameters — cordless infers the Discord option types and passes the values as arguments:

@bot.command("buy", description="Buy an item")
async def buy(ctx, item: str, qty: int = 1):
    await ctx.send(f"bought {qty}x {item}")

Parameters without a default are required. Supported annotations: str, int, float, bool.

For choices, autocomplete, users, channels, roles, or min/max constraints, use the option() helper:

from cordless import option

@bot.command("greet", description="Greet a user", options=[
    option("name", "Who to greet", required=True),
    option("times", "How many times", type="integer", min_value=1, max_value=5),
])
async def greet(ctx):
    await ctx.send(f"Hey, {ctx.options['name']}!")

Available types: string, integer, number, boolean, user, channel, role, attachment.

Subcommands

Use parent/sub paths — cordless builds the Discord subcommand tree automatically:

@bot.command("info/bot", description="About this bot")
async def info_bot(ctx): ...

@bot.command("info/server", description="About this server")
async def info_server(ctx): ...

Deferred commands

For commands that take more than 3 seconds, set defer=True. Requires defer_worker in cordless.toml.

@bot.command("slow", description="Takes a while", defer=True)
async def slow(ctx):
    result = await do_something_slow()
    await ctx.send(result)

Scheduled handlers

@bot.cron("rate(1 hour)")
async def hourly_tick():
    ...

Deploy wires these to EventBridge automatically — see Deploying to AWS.

Registering

# standalone
cordless register lambda_function:bot --token YOUR_BOT_TOKEN

# guild-only (faster propagation, for testing)
cordless register lambda_function:bot --token YOUR_BOT_TOKEN --guild-id YOUR_GUILD_ID

# or as part of deploy
cordless deploy --register lambda_function:bot