> For the complete documentation index, see [llms.txt](https://cjays-organization.gitbook.io/nexora.ts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cjays-organization.gitbook.io/nexora.ts/commands-and-interactions/commands.md).

# Commands

Define slash commands with the typed `command()` helper — or as a class. Files under your commands path are loaded automatically.

```ts
import { command } from '@nexora.ts/core';

export default command({
  name: 'ping',
  description: 'Ping the bot',
  options: [
    {
      name: 'echo',
      description: 'Optional text to echo',
      type: 'string',
      required: false,
    },
  ],
  async execute(ctx) {
    const echo = ctx.options.string('echo');
    await ctx.reply(echo ?? 'Pong!');
  },
});
```

## Context helpers

`execute` receives a `CommandContext` with Discord.js access **and** short helpers. Prefer working through `ctx.*` instead of wiring Discord replies (and, as the context system rolls out, logger/services) by hand:

| Field / method          | Description                                                         |
| ----------------------- | ------------------------------------------------------------------- |
| `interaction`           | Discord.js chat input interaction                                   |
| `client`                | Discord client                                                      |
| `user`                  | Invoking user                                                       |
| `guild`                 | Guild or `null` (DM)                                                |
| `member`                | Guild member or `null`                                              |
| `channel`               | Channel where the command ran                                       |
| `guildId`               | Guild id or `null`                                                  |
| `options.string/user/…` | Typed getters for slash options                                     |
| `reply(…)`              | Reply to the interaction (strings, discord.js options, or builders) |
| `embed(…)`              | Reply with a single embed builder / `APIEmbed`                      |
| `componentsV2(…)`       | Reply with Components V2 (sets `IS_COMPONENTS_V2` automatically)    |
| `defer(…)`              | Defer the reply (for longer work)                                   |
| `editReply(…)`          | Edit a deferred / previous reply                                    |
| `followUp(…)`           | Send a follow-up message                                            |

```ts
async execute(ctx) {
  const target = ctx.options.user('user', true);
  await ctx.reply(`Hello ${target.username}`);
}
```

You can still use `ctx.interaction.reply(…)` when you need the full Discord.js API.

```ts
async execute(ctx) {
  await ctx.defer();
  // … work …
  await ctx.editReply(`Done for ${ctx.user.username}`);
}
```

### Embeds & Components V2

`reply` accepts builder-friendly options: `embed` / `embeds`, `components`, and `v2` (auto flag). See [Builders](/nexora.ts/builders-and-ui/builders.md) and [Components V2](/nexora.ts/builders-and-ui/components-v2.md).

```ts
import { command, EmbedBuilder } from '@nexora.ts/core';

export default command({
  name: 'status',
  description: 'Show status',
  async execute(ctx) {
    await ctx.embed(EmbedBuilder.success('Online', 'Bot is ready.'));
  },
});
```

```ts
import { command, text, container } from '@nexora.ts/core';

export default command({
  name: 'panel',
  description: 'V2 status panel',
  async execute(ctx) {
    await ctx.componentsV2(
      container(text('# Online'), text('Bot is ready.')).accent(0x57f287),
    );
  },
});
```

## Guards

Guards run **before** `execute`. Failed checks reply with an ephemeral error.

| Option             | Behavior                                |
| ------------------ | --------------------------------------- |
| `guildOnly: true`  | Rejects DMs                             |
| `adminOnly: true`  | Requires Administrator permission       |
| `permissions: […]` | Requires the listed Discord permissions |
| `cooldown: number` | Per-user cooldown in **milliseconds**   |

```ts
export default command({
  name: 'purge',
  description: 'Delete messages',
  guildOnly: true,
  adminOnly: true,
  permissions: ['ManageMessages'],
  cooldown: 5_000,
  async execute(ctx) {
    await ctx.reply('Purging…');
  },
});
```

## Class style

Prefer classes when you want shared structure, reuse, or DI-friendly services. Discovery accepts both styles.

```ts
import { SlashCommand, type CommandContext } from '@nexora.ts/core';

export default class PingCommand extends SlashCommand {
  name = 'ping';
  description = 'Check bot latency';
  guildOnly = true;
  cooldown = 3_000;

  async execute(ctx: CommandContext) {
    await ctx.reply('Pong!');
  }
}
```

### Groups, menus & prompts

| Need                                  | Class / helper                                                                 |
| ------------------------------------- | ------------------------------------------------------------------------------ |
| Subcommands under one root            | [SlashCommandGroup](/nexora.ts/framework/slash-command-group.md)               |
| User / message context menu           | [ContextMenuCommand](/nexora.ts/framework/slash-command-group.md)              |
| Persistent buttons / selects / modals | [ButtonHandler](/nexora.ts/framework/button-handler.md) (+ `interactions/`)    |
| Paginated embeds, confirm, choice     | [Paginator](/nexora.ts/message-ui/paginator.md) · ConfirmDialog · ChoicePrompt |

See [Classes](/nexora.ts/classes/index.md) for `SlashCommand`, groups, handlers, builders, and plugins with full examples.

## Options

Supported option types: `string`, `integer`, `boolean`, `user`, `channel`, `role`, `mentionable`, `number`.

## Deployment

On startup, Nexora deploys registered commands to configured guilds (or globally if no `guildIds` are set).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cjays-organization.gitbook.io/nexora.ts/commands-and-interactions/commands.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.