Adding Commands

This guide walks through creating a new slash command in Annie Mei, following the project’s conventions and patterns.

Command Structure

All commands follow a consistent pattern with two main functions:

register() - Defines the slash command structure for Discord
run() - Executes the command logic when invoked

Commands can be simple single-file modules or complex multi-file modules with subcommands.

Creating a Simple Command

Let’s create a /ping style command as an example.

Create the Command Module

Create a new file in src/commands/:

touch src/commands/example.rs

For complex commands, create a directory:

mkdir -p src/commands/example
touch src/commands/example/{mod.rs,command.rs}

Implement register() Function

Define the slash command structure that Discord will display to users:

src/commands/example.rs

use serenity::builder::CreateCommand;

pub fn register() -> CreateCommand {
    CreateCommand::new("example")
        .description("An example command")
}

This creates a basic command with no options.

Implement run() Function

Add the command execution logic:

src/commands/example.rs

use serenity::{
    all::{CommandInteraction, CreateInteractionResponse, CreateInteractionResponseMessage},
    prelude::*,
};
use tracing::info;

pub async fn run(ctx: &Context, interaction: &CommandInteraction) {
    info!("Received example command");

    let message = CreateInteractionResponseMessage::new()
        .content("Hello from example command!");
    let response = CreateInteractionResponse::Message(message);

    let _ = interaction.create_response(&ctx.http, response).await;
}

Export in mod.rs

Add your new command to src/commands/mod.rs:

src/commands/mod.rs

pub mod anime;
pub mod character;
pub mod help;
pub mod input_validation;
pub mod manga;
pub mod ping;
pub mod recommend;
pub mod register;
pub mod response;
pub mod search;
pub mod songs;
pub mod traits;
pub mod unregister;
pub mod whoami;
pub mod example;  // Add this line

Add your command to the registration list in src/main.rs at the ready event handler:

src/main.rs

async fn ready(&self, ctx: Context, ready: Ready) {
    let commands: Vec<CreateCommand> = vec![
        commands::ping::register(),
        commands::help::register(),
        commands::songs::command::register(),
        commands::manga::command::register(),
        commands::anime::command::register(),
        commands::search::command::register(),
        commands::recommend::command::register(),
        commands::character::command::register(),
        commands::register::command::register(),
        commands::unregister::register(),
        commands::whoami::register(),
        commands::example::register(),  // Add this line
    ];

    let guild_commands = Command::set_global_commands(&ctx.http, commands).await;
    // ...
}

See src/main.rs for the full implementation.

Add Match Arm in interaction_create

Route the command to your handler in src/main.rs at the interaction_create event:

src/main.rs

match command.data.name.as_str() {
    "ping" => commands::ping::run(&ctx, &command).await,
    "help" => commands::help::run(&ctx, &command).await,
    "songs" => commands::songs::command::run(&ctx, &mut command).await,
    "manga" => commands::manga::command::run(&ctx, &mut command).await,
    "anime" => commands::anime::command::run(&ctx, &mut command).await,
    "search" => commands::search::command::run(&ctx, &mut command).await,
    "recommend" => commands::recommend::command::run(&ctx, &mut command).await,
    "character" => commands::character::command::run(&ctx, &mut command).await,
    "register" => commands::register::command::run(&ctx, &mut command).await,
    "unregister" => commands::unregister::run(&ctx, &mut command).await,
    "whoami" => commands::whoami::run(&ctx, &mut command).await,
    "example" => commands::example::run(&ctx, &mut command).await,  // Add this line
    _ => {
        // Error handler...
    }
};

See src/main.rs for the full implementation.

Adding Command Options

Commands can accept user input through options:

use serenity::{
    all::CreateCommandOption,
    builder::CreateCommand,
    model::application::CommandOptionType,
};

pub fn register() -> CreateCommand {
    CreateCommand::new("search")
        .description("Search for something")
        .add_option(
            CreateCommandOption::new(
                CommandOptionType::String,
                "query",
                "What to search for",
            )
            .required(true),
        )
        .add_option(
            CreateCommandOption::new(
                CommandOptionType::Integer,
                "limit",
                "Maximum number of results",
            )
            .required(false)
            .min_int_value(1)
            .max_int_value(25),
        )
}

Accessing Option Values

Extract option values in your run() function:

pub async fn run(ctx: &Context, interaction: &mut CommandInteraction) {
    // Get required string option
    let Some(serenity::all::CommandDataOptionValue::String(query)) =
        interaction.data.options.first().map(|opt| &opt.value)
    else {
        let builder = EditInteractionResponse::new()
            .content("Missing required 'query' option");
        let _ = interaction.edit_response(&ctx.http, builder).await;
        return;
    };

    // Get optional integer option
    let limit = interaction.data.options
        .get(1)
        .and_then(|opt| match &opt.value {
            serenity::all::CommandDataOptionValue::Integer(val) => Some(*val),
            _ => None,
        })
        .unwrap_or(10);  // Default value

    info!("Search query: {}, limit: {}", query, limit);
    // Command logic...
}

See src/commands/anime/command.rs:66-80 for a real-world example.

Deferring Long Operations

Discord requires responses within 3 seconds. For long-running operations, defer the response immediately:

#[instrument(name = "command.example.run", skip(ctx, interaction))]
pub async fn run(ctx: &Context, interaction: &mut CommandInteraction) {
    // Defer immediately
    let _ = interaction.defer(&ctx.http).await;

    // Long operation (e.g., async API call or database query)
    let result = fetch_example_data().await;

    // Edit the deferred response
    let builder = EditInteractionResponse::new()
        .content("Operation complete!");
    let _ = interaction.edit_response(&ctx.http, builder).await;
}

Always defer before operations that take longer than 3 seconds, including external API calls and database queries.

Calling external services

External API clients use async reqwest::Client. Await those requests directly after deferring the Discord interaction:

use tracing::error;

let result = match client
    .post("https://graphql.anilist.co/")
    .header("Content-Type", "application/json")
    .body(query_json.to_string())
    .send()
    .await
{
    Ok(response) => Some(response),
    Err(error) => {
        error!(error = %error, "API request failed");
        None
    }
};

Use spawn_blocking only for synchronous work that can block the Tokio runtime, such as the current Redis cache helper calls. See src/utils/requests/anilist.rs for the AniList HTTP client and src/commands/recommend/command.rs for a bounded spawn_blocking cache example.

Adding Instrumentation

Use the #[instrument] attribute for tracing and observability:

use tracing::{info, instrument};

#[instrument(name = "command.example.run", skip(ctx, interaction))]
pub async fn run(ctx: &Context, interaction: &mut CommandInteraction) {
    info!("Processing example command");
    // Command logic...
}

This creates a tracing span that appears in logs and Sentry:

name - Span name for filtering
skip - Fields to exclude from tracing (avoid logging sensitive data)

Code Style Conventions

Follow these conventions when writing commands:

Logging

Use tracing macros: info!, debug!, error!Never use println! or eprintln!

Error Handling

Prefer ? operator over .unwrap()Handle errors gracefully with user-friendly messages

Privacy

Hash user IDs before logging:

use crate::utils::privacy::hash_user_id;

let hashed = hash_user_id(user.id.get());

Sentry

Configure Sentry scope for commands:

use crate::utils::privacy::configure_sentry_scope;

configure_sentry_scope("Example", user.id.get(), None);

Testing Your Command

Unit Tests

Add tests in the same file:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_command_logic() {
        // Test your command's core logic
        assert_eq!(2 + 2, 4);
    }
}

See src/commands/ping.rs:50-78 for a complete test example.

Running Tests

cargo test

Run tests for a specific module:

cargo test --test example

Manual Testing

Run the bot locally:
cargo run
Use the command in Discord:
/example
Check logs for tracing output:
RUST_LOG=debug cargo run

Example: Complete Command

Here’s a complete command implementation from src/commands/ping.rs:

use crate::utils::privacy::configure_sentry_scope;
use super::response::CommandResponse;

use serenity::{
    all::{CommandInteraction, CreateInteractionResponse, CreateInteractionResponseMessage},
    builder::CreateCommand,
    prelude::*,
};

pub fn register() -> CreateCommand {
    CreateCommand::new("ping").description("A ping command")
}

// Core logic (transport-agnostic, testable)
pub fn handle_ping(user_mention: &str) -> CommandResponse {
    CommandResponse::Message(format!(
        "Hello {user_mention}! I'm Annie Mei, a bot that helps you find anime and manga!",
    ))
}

// Serenity adapter (thin wrapper)
pub async fn run(ctx: &Context, interaction: &CommandInteraction) {
    let user = &interaction.user;
    configure_sentry_scope("Ping", user.id.get(), None);

    let reply = handle_ping(&user.mention().to_string());

    let text = match reply {
        CommandResponse::Message(text) => text,
        _ => unreachable!("/ping always returns Message"),
    };

    let response_message = CreateInteractionResponseMessage::new().content(text);
    let response = CreateInteractionResponse::Message(response_message);

    let _ = interaction.create_response(&ctx.http, response).await;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn ping_happy_path_returns_message_with_greeting() {
        let response = handle_ping("<@123456>");
        assert!(response.is_message());
        let text = response.unwrap_message();
        assert!(text.contains("<@123456>"));
        assert!(text.contains("Annie Mei"));
    }
}

File Organization Patterns

Depending on complexity, organize your command:

Simple Command (Single File)

src/commands/ping.rs

Use for commands with minimal logic and no external queries.

Complex Command (Module)

src/commands/anime/
├── mod.rs          # Re-exports
├── command.rs      # register() and run()
└── queries.rs      # GraphQL queries

Use for commands with:

GraphQL queries
Multiple helper functions
Complex business logic

See src/commands/anime/ for a complete example.

Next Steps

Architecture

Understand the project structure

Database

Add database models for persistent data

Testing

Write comprehensive tests

Getting Started

Self-hosting

Commands

Legal

Development

Deployment

API Reference

Command Structure

Creating a Simple Command

Adding Command Options

Accessing Option Values

Deferring Long Operations

Calling external services

Adding Instrumentation

Code Style Conventions

Logging

Error Handling

Privacy

Sentry

Testing Your Command

Unit Tests

Running Tests

Manual Testing

Example: Complete Command

File Organization Patterns

Simple Command (Single File)

Complex Command (Module)

Next Steps

Architecture

Database

Testing

​Command Structure

​Creating a Simple Command

​Adding Command Options

​Accessing Option Values

​Deferring Long Operations

​Calling external services

​Adding Instrumentation

​Code Style Conventions

Logging

Error Handling

Privacy

Sentry

​Testing Your Command

​Unit Tests

​Running Tests

​Manual Testing

​Example: Complete Command

​File Organization Patterns

​Simple Command (Single File)

​Complex Command (Module)

​Next Steps

Architecture

Database

Testing

Command Structure

Creating a Simple Command

Adding Command Options

Accessing Option Values

Deferring Long Operations

Calling external services

Adding Instrumentation

Code Style Conventions

Testing Your Command

Unit Tests

Running Tests

Manual Testing

Example: Complete Command

File Organization Patterns

Simple Command (Single File)

Complex Command (Module)

Next Steps