Command Aliases

Command aliases are alternative names for your commands. They let users trigger the same command using different names, making your bot more discoverable and easier to use. Think of aliases as shortcuts or synonyms—users might expect /hi to work the same as /hello, and aliases let you provide that flexibility without duplicating code.

Aliases are particularly useful for improving user experience. Some users prefer shorter commands (/ls vs /list), others might think in different languages (/help vs /ajuda), and some might just make typos. Aliases accommodate all these scenarios, making your bot feel more natural and forgiving.

What Are Aliases?

Aliases are alternative names for a command. When you define aliases, users can trigger the same handler using any of the names you've specified. This is powerful because it lets you support multiple ways of expressing the same intent without writing separate handlers.

greet: {
  name: 'greet',
  aliases: ['hello', 'hi', 'hey'],
  description: 'Greet the user',
  help: 'Use /greet, /hello, /hi, or /hey',
  async handle(ctx) {
    await ctx.bot.send({
      provider: ctx.provider,
      channel: ctx.channel.id,
      content: {
        type: 'text',
        content: '👋 Hello!'
      }
    })
  }
}

Now users can use:

• /greet
• /hello
• /hi
• /hey

All of these will trigger the same handler.

How Aliases Work

The bot maintains an internal index that maps both command names and aliases to the same handler. This index is built when commands are registered, so alias resolution is fast—it happens in O(1) time. The resolution is also case-insensitive, so /GREET and /greet work the same way.

Common Use Cases

There are several common scenarios where aliases shine. Understanding these patterns helps you decide when and how to use aliases effectively in your bot. Each use case demonstrates a different way aliases improve user experience:

Examples

Here are complete examples showing how aliases work in real-world scenarios. These examples demonstrate different use cases and help you understand how to apply aliases effectively in your own bots. Each example shows practical patterns you can adapt for your specific needs.

Aliases vs Separate Commands

Sometimes you might wonder: should I use aliases or create separate commands?

Use aliases when:

• Commands do exactly the same thing
• You want to provide alternative names for convenience
• Commands share the same logic

Create separate commands when:

• Commands have different behavior
• Commands need different parameters
• Commands should have different help text

Example: When to Use Separate Commands

// ❌ Don't use aliases for different behaviors
commands: {
  start: {
    name: 'start',
    aliases: ['stop'], // These do different things!
    // ...
  }
}

// ✅ Use separate commands
commands: {
  start: {
    name: 'start',
    aliases: ['begin', 'go'],
    // Start logic...
  },
  stop: {
    name: 'stop',
    aliases: ['end', 'quit'],
    // Stop logic...
  }
}

Resolving Commands

When a user sends a command, the bot resolves it like this:

1. Check if it's a command name (case-insensitive)
2. If not found, check if it's an alias (case-insensitive)
3. If found, execute the handler
4. If not found, emit an error event

// User sends: /hello
// Bot checks: 'hello' is an alias for 'greet'
// Bot executes: greet handler

// User sends: /unknown
// Bot checks: 'unknown' is not a command or alias
// Bot emits: COMMAND_NOT_FOUND error

Limitations

Understanding the limitations of aliases helps you make informed decisions about when to use them and when to consider alternatives. These constraints exist by design—they keep the system simple and predictable, but they also mean aliases aren't a solution for every scenario.

Best Practices

Following these practices helps you create aliases that genuinely improve user experience rather than adding confusion. Good aliases feel natural and predictable, while bad aliases can make your bot harder to use.