Commands

Commands are the main way to interact with your bot, including Context Menu apps and slash commands.

Commands are the main way to interact with your bot. They are used to handle user input and respond to it.

Creating a Command

To create a command, you need to create a class that extends the Command class. This class will handle the command and its functionality.

src/commands/ping.ts

import { Command, type CommandInteraction } from "@buape/carbon";

export default class PingCommand extends Command {
    name = "ping"
    description = "A simple ping command"

    async run(interaction: CommandInteraction) {
        await interaction.reply("Pong!")
    }
}

In this example, we have created a simple command that responds with "Pong" when the user runs the command.

Setting the Name and Description

The name and description properties are used to set the name and description of the command. These are used in the help command and in the command list.

Setting the Type

The type property is used to set the type of the command. This is used to determine which type of command it is. The available types are:

ChatInput: This is a command that can be used in a chat input.
User: This is a command that can be used in a user context.
Message: This is a command that can be used in a message context.

Options

The options property is used to set the options of the command. These are only used for chat input commands.

String: Basic string input
Integer: Integer input
Number: Number input
Boolean: Boolean input (with autocomplete to show True and False)
User: User object (with autocomplete to show users in the server. Also accepts just an ID which will be resolved to a user object)
Channel: Channel object (with autocomplete to show channels in the server. Also accepts just an ID which will be resolved to a channel object)
Role: Role object (with autocomplete to show roles in the server. Also accepts just an ID which will be resolved to a role object)
Mentionable: Mentionable object (with autocomplete to show both users and roles in the server)
Attachment: File attachment

Autocomplete

You can provide autocomplete functionality for your command options in two ways:

Command-level Autocomplete

For basic cases, you can use the autocomplete method on your command class:

src/commands/search.ts

import { Command, type CommandInteraction, type AutocompleteInteraction } from "@buape/carbon";

export default class SearchCommand extends Command {
    name = "search"
    description = "Search for something"
    
    options = [
        {
            name: "query",
            type: ApplicationCommandOptionType.String,
            description: "What to search for",
            required: true,
            autocomplete: true
        }
    ]

    async autocomplete(interaction: AutocompleteInteraction) {
        const focusedOption = interaction.options.getFocused()
        // Provide autocomplete choices based on the focused option
        await interaction.respond([
            { name: "Option 1", value: "value1" },
            { name: "Option 2", value: "value2" }
        ])
    }

    async run(interaction: CommandInteraction) {
        // Handle the command
    }
}

Option-level Autocomplete

For better organization and reusability, you can define autocomplete handlers directly on individual options:

src/commands/search.ts

import { Command, type CommandInteraction, type AutocompleteInteraction } from "@buape/carbon";

export default class SearchCommand extends Command {
    name = "search"
    description = "Search for something"
    
    options = [
        {
            name: "query",
            type: ApplicationCommandOptionType.String,
            description: "What to search for",
            required: true,
            autocomplete: async (interaction: AutocompleteInteraction) => {
                const userInput = String(interaction.options.getFocused())
                await interaction.respond([
                    { name: `Search for: ${userInput}`, value: userInput },
                    { name: `Advanced search: ${userInput}`, value: `advanced:${userInput}` }
                ])
            }
        },
        {
            name: "category",
            type: ApplicationCommandOptionType.String,
            description: "Category to search in",
            required: false,
            autocomplete: async (interaction: AutocompleteInteraction) => {
                await interaction.respond([
                    { name: "General", value: "general" },
                    { name: "Technical", value: "tech" },
                    { name: "Entertainment", value: "entertainment" }
                ])
            }
        }
    ]

    async run(interaction: CommandInteraction) {
        // Handle the command
    }
}

When an option has its own autocomplete function, it will be used instead of the command-level autocomplete method. This allows for better organization and reusability of autocomplete logic across multiple commands.

Adding your Components

The components property is used to set the components of the command. You need to pass every component that you might use in the command, and they will be automatically registered.

See this page for more information about components.

Automatic Defer

The defer property is used to set whether the command should be deferred automatically. When a command is deferred, it will show a Loading state to the user, and you have 15 minutes to reply after that.

Wildcard Commands

You can also create a wildcard command, which will be called when no command is found. This is useful for when you want to have a default command that is called when no other command is found, or for something like a maintenance mode for another bot that you can switch to.

To create a wildcard command, you just have to create a command like normal, but set the name to "*". This will be called when no other command is found.

src/commands/_maintenance.ts

import { Command, type CommandInteraction } from "@buape/carbon";

export default class MaintenanceCommand extends Command {
    name = "*"
    description = "Maintenance mode"
    defer = false

    async run(interaction: CommandInteraction) {
        await interaction.reply(
            "The bot is currently under maintenance. Please try again later."
        )
    }
}

On this page