Declaring a command

This page covers the discord command structure itself: its header, its entries, how a message is matched against it, and what the trigger can read. You're assumed to have a bot named "my-bot" logged in (see Starting a bot) and to have read the commands overview.

How a command works

A discord command is a top-level structure, declared next to your bot's on ready and options: blocks, not inside them. Its header names the command; its trigger runs once a message matches. The bot watches every message it receives and compares it against every loaded command.

discord command ping:
    prefixes: "!"
    trigger:
        reply with "pong"

Sending !ping runs the trigger above. Matching works like this: the command's name is compared case-insensitively, the message must start with <prefix><name> (in that order), and anything after that, separated by whitespace, becomes the raw arguments. A message sent by another bot, or by a webhook, never triggers a command. Without an executable in entry (see Restricting a command), a command works in DMs as well as in guild channels.

Entries

Every entry below except trigger is optional.

roles, permissions, bots, executable in, cooldown and cooldown scope restrict who can run the command; see Restricting a command. usage message is covered with the rest of the argument grammar on Arguments.

Prefixes and aliases

A command declared without prefixes: answers to its bare name, nothing in front of it:

discord command hello <user>:
    trigger:
        reply with "Hello %arg-1%!"

prefixes accepts more than one value, so a command can answer to several:

discord command ping:
    prefixes: "!", "?"
    trigger:
        reply with "pong"

prefixes is an expression, evaluated fresh for every incoming message, not a fixed list read once at load time. A prefix stored in a variable can therefore change while the script runs:

discord command ping:
    prefixes: "%{prefix}%"
    trigger:
        reply with "pong"

The entry is parsed before the command's event exists, so event values such as event-guild cannot be used inside it; a per-guild prefix is not possible through prefixes alone.

Once a message matches, used prefix and used alias report exactly what matched, name or alias:

discord command ping:
    prefixes: "!"
    aliases: p, pong
    trigger:
        reply with "matched with '%used prefix%%used alias%'"

Inside the trigger

The trigger of a discord command is itself an event: everything below is readable there, and in on discord command used and on discord command failed too.

Declared arguments are read with arg-1 and friends; see Arguments. reply with posts in event-channel, the command's own channel, and every ordinary DiSky effect works in the trigger exactly as it does in on message received.

Reloading and clashes

Commands are registered by identity, not by name: reloading a script removes only the commands it declared, and never touches another script's. Two commands sharing a name (or an alias) with overlapping prefixes both still load, with a warning:

The discord command '<name>' is already declared in <file>; both will run on the same message.

Errors you may see

Declaring a command never talks to Discord, so it has no Discord-side errors of its own; those start once a message actually reaches the trigger (see Errors).