> ## Documentation Index > Fetch the complete documentation index at: https://www.chapterjs.org/llms.txt > Use this file to discover all available pages before exploring further. # command() > Everything a command file declares, every kind of option, menu commands, and what the run function receives `command()` declares a slash command, from any file of `src/`; its `name` is what people type after the `/`. It takes one object, `CommandConfig`, and types `run` from it. With a `type`, it declares a [menu command](#menu-commands) instead, used with a right click on a message or a person. ```ts src/commands/ping.ts theme={"theme":{"light":"github-light","dark":"vesper"}} import { command } from 'chapterjs'; export default command({ name: 'ping', description: 'Replies with Pong!', async run({ interaction }) { await interaction.reply('Pong!'); }, }); ``` > [!NOTE] > > How to write a command, its options, its answers and its translations is in the [guide](https://www.chapterjs.org/commands.md), and menu commands in [their own page](https://www.chapterjs.org/commands/menus.md). This page lists what exists. ## command() ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} command( config: Type extends MenuType ? MenuConfig : CommandConfig ): Type extends MenuType ? MenuDeclaration : CommandDeclaration ``` Declares a command. Export the result from any file of `src/`. A slash command: `name` is what people type after the `/` (`'mod ban'` for `/mod ban`). A menu command, with `type`: used with a right click on a message (`'message'`) or on a person (`'user'`), `name` being what the menu shows. `Options`, `Where` and `Type` are inferred from what you pass: you never write them. ### CommandDeclaration ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} interface CommandDeclaration ``` What `command()` returns: a declaration the framework finds in the exports of a file. It keeps the options and the place the file declared. **config** `CommandConfig\` What the file gave to `command()`, not checked yet. ## CommandConfig What a file gives to `command()`: what the command is and does. **name** `CommandName` *required* What people type after the `/`: `'ping'` is `/ping`. A subcommand is written with its parents: `'mod ban'` is `/mod ban`, `'mod roles add'` is `/mod roles add`. **description** `string` What the command does, shown under its name (1-100 characters). Here, with `locales` for its translations; or left out, and every text of the command (description, options, their choices, translations) comes from the language files of the project. One or the other. **run** `(context: CommandContext\) =\> unknown` *required* What to do when someone uses the command. **options** `CommandOptions` What the user can fill in (25 options at most). **locales** `CommandLocales\` The command in other languages: Discord shows each person the names and descriptions of their language. Your code always receives the names declared above, whatever the language. [Discord documentation](https://docs.discord.com/developers/interactions/application-commands#localization) **permissions** `readonly PermissionName[]` The permissions a member needs to use the command. Server admins can change who sees it in the server settings. **where** `CommandWhere` Where the command can be used: `'guild'` (in servers, the default), `'dm'` (in private messages with the bot) or `'both'`. What `run` receives follows it. **nsfw** `boolean` Only show the command in age-restricted channels. **ephemeral** `boolean` Make the answers of the command only visible to who used it. **cooldown** `Cooldown` How long to wait before the command can be used again: `'10s'` for each person, or `{ user, channel, guild }` for each place. Someone who uses it too soon gets a private answer saying when they can. **autocomplete** `CommandAutocomplete\` Suggestions that come from your bot while the person types, for the options named here (a `string`, `integer` or `number` option without `choices`): each function receives what they typed and returns the suggestions. The person may still type something else. **type** `undefined` Leave it out for a slash command. `'message'` or `'user'` makes a menu command instead, used with a right click on a message or a person. ### CommandName ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} type CommandName = string ``` The name of a slash command: lowercase letters, digits, `-` and `_`, 32 characters at most (`'ping'`). A subcommand is written with its parents, separated by spaces: `'mod ban'` is `/mod ban`, `'mod roles add'` is `/mod roles add` (Discord allows nothing deeper). ### CommandWhere ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} CommandWhere = 'guild' | 'dm' | 'both' ``` Where a command can be used: in servers (`'guild'`), in private messages with the bot (`'dm'`), or in both. [Discord documentation](https://docs.discord.com/developers/interactions/application-commands#interaction-contexts) ### Cooldown ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} Cooldown = Duration | { readonly user?: Duration; readonly channel?: Duration; readonly guild?: Duration } ``` How long to wait before the command can be used again: a duration, for each person; or one per place, each optional: `user` for each person, `channel` for each channel, `guild` for each server (not for a command of private messages). Someone who uses it too soon gets a private answer saying when they can, and `run` does not run. **user** `Duration` Each person waits this long between two uses, wherever they are. **channel** `Duration` Each channel waits this long, whoever used it. **guild** `Duration` Each server waits this long, whoever used it, wherever. ### Duration ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} Duration = `${number}${'s' | 'm' | 'h' | 'd'}${string}` ``` A duration, as a number and a unit: `s`, `m`, `h` or `d`, like `'30s'`, `'10m'`, `'2h'`, `'1d'`. Several parts add up: `'1h30m'`. ## The options ### CommandOptions ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} CommandOptions = Readonly> ``` The options of a command, by name. A name is made of lowercase letters, digits, `-` and `_`, 32 characters at most. ### CommandOption ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} CommandOption = StringOption | NumberOption | ChannelOption | SimpleOption ``` One option of a command. Every kind has these fields: **type** `string` *required* The kind of option: `'string'`, `'integer'`, `'number'`, `'boolean'`, `'user'`, `'role'`, `'channel'`, `'mentionable'` or `'attachment'`. **description** `string` What the option is for, shown under its name (1-100 characters). Here when the command has its `description` here; otherwise in the default language file of the project. **required** `boolean` Whether the user must fill it in. By default it is optional. ### StringOption A text the user types, or picks among `choices`. **type** `'string'` *required* The kind of option: a text. **choices** `readonly string[] | Readonly\\>` The only values the user can pick (25 at most): a list, or an object whose keys are what the user sees and values what your code receives. **minLength** `number` The shortest text accepted, in characters (0 to 6000). **maxLength** `number` The longest text accepted, in characters (1 to 6000). ### NumberOption A whole number (`integer`) or any number (`number`). **type** `'integer' | 'number'` *required* The kind of option: a whole number, or any number. **choices** `readonly number[] | Readonly\\>` The only values the user can pick (25 at most): a list, or an object whose keys are what the user sees and values what your code receives. **min** `number` The smallest value accepted. **max** `number` The largest value accepted. For an `'integer'` option, `min`, `max` and the choices must be whole numbers. ### ChannelOption A channel the user picks. **type** `'channel'` *required* The kind of option: a channel. **channelTypes** `readonly ChannelType[]` The kinds of channels that can be picked. By default, all of them. The values are those of [`ChannelType`](https://www.chapterjs.org/reference/enums#channeltype). ### SimpleOption True or false, a user, a role, a user or a role, or a file. **type** `'boolean' | 'user' | 'role' | 'mentionable' | 'attachment'` *required* The kind of option: what the user picks. ### OptionValuesOf ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} OptionValuesOf ``` The values of the options, typed from their declaration: a required option is always there, an optional one may be `undefined`. It is the type of `options` in `run`. | `type` | Value | | - | - | | `'string'` | `string` | | `'integer'` | `number` | | `'number'` | `number` | | `'boolean'` | `boolean` | | `'user'` | [`User`](https://www.chapterjs.org/reference/user) | | `'role'` | [`Role`](https://www.chapterjs.org/reference/role) | | `'channel'` | [`Channel`](https://www.chapterjs.org/reference/channels) | | `'mentionable'` | `User \| Role` | | `'attachment'` | [`Attachment`](https://www.chapterjs.org/reference/data#attachment) | With `choices`, the value is the union of the choices: `'red' | 'green'` for `choices: ['red', 'green']`, `1 | 2` for `choices: { Small: 1, Large: 2 }`. ## Autocomplete ### CommandAutocomplete ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} CommandAutocomplete ``` The `autocomplete` of a command: one function per option whose suggestions come from your bot while the person types, by the name of the option. Only a `string`, `integer` or `number` option without `choices` can have one. The function returns the suggestions (25 at most, Discord shows them in that order), or a promise of them: Discord waits 3 seconds. The person may still type something else. ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} { readonly [Name in ]?: ( context: AutocompleteContext ) => readonly Suggestion[] | Promise[]>; } ``` `Value` is `string` for a `string` option, `number | undefined` for an `integer` or `number` option in the context, and `string` or `number` in the suggestions. When no option can have suggestions, no key is accepted, and the editor says why. [Discord documentation](https://docs.discord.com/developers/interactions/application-commands#autocomplete) ### AutocompleteContext ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} AutocompleteContext ``` What an `autocomplete` function receives, each time the person types in its option. Nothing of it can be answered: the suggestions are what the function returns. **value** `Value` *required* What the person has typed so far in the option: a text, maybe empty, for a `string` option; for an `integer` or `number` option, a number, or `undefined` while what they typed is not one yet. **options** `OptionsSoFar\` *required* What the person has filled in so far, this option included. **user** `User` *required* Who is typing. **locale** `Locale` *required* The language of the person: suggest in it when you can. **t** `Translator` The texts of the project in the language of the person, when the project has a language. See [`Translator`](https://www.chapterjs.org/reference/messages#translator). The place follows `where`, like [`CommandContext`](#commandcontext) without its `interaction`: in a server `guild`, `member` and `channel` ([`CommandInGuild`](#commandinguild)); in private messages only `channel` ([`CommandInDm`](#commandindm)); with `'both'`, `if (guild)` tells which one it is ([`CommandInPrivate`](#commandinprivate)). ### OptionsSoFar ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} OptionsSoFar ``` The options as the person has filled them in so far, while they type in one of them: every option may be missing, a `user`, `role`, `channel`, `mentionable` or `attachment` option is its id. ### Suggestion ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} Suggestion = Value | { name: string; value: Value } ``` One suggestion for an option: a value, shown as is, or `{ name, value }` to show a text (1-100 characters) and receive another value. The value is a text (100 characters at most) for a `string` option, a number for an `integer` or `number` option. **name** `string` *required* What the person sees in the list (1-100 characters). **value** `Value` *required* What your `run` receives when they pick it. ## What run receives ### CommandContext ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} CommandContext ``` What the `run` function of a command receives. It follows `where`: in a server, the server, the member and the channel are there; in private messages they do not exist; in both, `if (guild)` tells which one it is, for everything at once. Whatever `where` says, it has: **options** `OptionValuesOf\` *required* What the user filled in. **user** `User` *required* Who used the command. **t** `Translator` The texts of the language files, in the right language. Only when the project has a language: see [`TranslationContext`](https://www.chapterjs.org/reference/messages#translationcontext). And the rest follows `where`: | `where` | The rest of the context | | - | - | | `'guild'` (the default) | `CommandInGuild` | | `'dm'` | `CommandInDm` | | `'both'` | `CommandInGuild \| CommandInPrivate` | ### CommandInGuild What a command used in a server receives about where it was used. **interaction** `GuildCommandInteraction` *required* The use of the command: what to answer with. **guild** `Guild` *required* The server the command was used in. **member** `GuildMember` *required* Who used the command, as a member of the server. **channel** `GuildTextBasedChannel` *required* The channel the command was used in. ### CommandInDm What a command only used in private messages receives: no server. **interaction** `DmCommandInteraction` *required* The use of the command: what to answer with. **channel** `DMChannel` *required* The private conversation the command was used in. ### CommandInPrivate What a command that works in both places receives when it is used in a private message: `guild` is `null`, and checking it tells the rest. **interaction** `PrivateCommandInteraction` *required* The use of the command: what to answer with. **guild** `null` *required* No server: the command was used in a private message. **member** `null` *required* No member: the person is `user`. **channel** `DMChannel` *required* The private conversation the command was used in. The interactions themselves are described in [Interaction](https://www.chapterjs.org/reference/interaction.md). ## Translations ### CommandLocales ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} CommandLocales = { readonly [Language in Locale]?: CommandTranslation; } ``` The translations of a command, by language. The keys are the values of [`Locale`](https://www.chapterjs.org/reference/enums#locale): `fr`, `de`, `es-ES`... ### CommandTranslation The translation of a command in one language. Everything is optional: what is not translated is shown as declared. **name** `string` The name of the command in that language (same rules as a name). **description** `string` The description of the command in that language (1-100 characters). **options** `\{ readonly [Name in keyof Options]?: OptionTranslation \}` The translation of each option, by the name declared in `options`. ### OptionTranslation The translation of one option. Everything is optional. **name** `string` The name of the option in that language (same rules as a name). **description** `string` The description of the option in that language (1-100 characters). **choices** `\{ readonly [Choice: string]?: string \}` What each choice is called in that language. The keys are the choices as declared: the values of a list, or the keys of an object. Each value is 1 to 100 characters. ## Menu commands ```ts src/commands/quote.ts theme={"theme":{"light":"github-light","dark":"vesper"}} import { command } from 'chapterjs'; export const quote = command({ type: 'message', name: 'Quote', async run({ interaction, message }) { await interaction.reply(`> ${message.content}`); }, }); ``` ### MenuType ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} type MenuType = 'message' | 'user'; ``` What a menu command is used on, in the menu people open with a right click (or a long press): a message (`'message'`) or a person (`'user'`). [Discord documentation](https://docs.discord.com/developers/interactions/application-commands#application-command-object-application-command-types) ### MenuConfig ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} interface MenuConfig ``` What a file gives to `command()` for a menu command: one used on a message or a person, from the menu of a right click. It has no description and no options: what it receives is what it was used on. **type** `Type` *required* What the command is used on: `'message'` (a right click on a message) or `'user'` (a right click on a person). **name** `string` *required* What the menu shows (1-32 characters): capitals and spaces are fine, like `'Report message'`. **run** `(context: MenuContext\) =\> unknown` *required* What to do when someone uses the command. **locales** `MenuLocales` The name in other languages: Discord shows each person the name of their language. [Discord documentation](https://docs.discord.com/developers/interactions/application-commands#localization) **permissions** `readonly PermissionName[]` The permissions a member needs to use the command. Server admins can change who sees it in the server settings. **where** `CommandWhere` Where the command can be used: `'guild'` (in servers, the default), `'dm'` (in private messages with the bot) or `'both'`. What `run` receives follows it. **nsfw** `boolean` Only show the command in age-restricted channels. **ephemeral** `boolean` Make the answers of the command only visible to who used it. **cooldown** `Cooldown` How long to wait before the command can be used again: `'10s'` for each person, or `{ user, channel, guild }` for each place. **description** `never` A menu command has no description: Discord only shows its name. **options** `never` A menu command has no options: it receives what it was used on. **autocomplete** `never` A menu command has no options to suggest values for. ### MenuDeclaration ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} interface MenuDeclaration ``` What `command()` returns for a menu command. **config** `MenuConfig\` What the file gave to `command()`, not checked yet. ### MenuContext ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} type MenuContext ``` What the `run` function of a menu command receives: what it was used on (`message`, or `target` and `targetMember`), who used it, and the place, which follows `where` like the one of a slash command ([`CommandInGuild`](#commandinguild), [`CommandInDm`](#commandindm), [`CommandInPrivate`](#commandinprivate)). **user** `User` *required* Who used the menu. **message** `GuildMessage | PrivateMessage | DmMessage` With `type: 'message'`: the message the menu was used on. A `GuildMessage` in a server, a `PrivateMessage` in a private message of a `where: 'both'` command, a `DmMessage` with `where: 'dm'`. **target** `User` With `type: 'user'`: the person the menu was used on. **targetMember** `GuildMember | null` With `type: 'user'`, in a server: that person as a member of the server, or `null` when they are not in it (any more). `null` in a private message; absent with `where: 'dm'`. **t** `Translator` The texts of the language files, in the right language. Only when the project has a language: see [`TranslationContext`](https://www.chapterjs.org/reference/messages#translationcontext). ### MenuLocales ```ts theme={"theme":{"light":"github-light","dark":"vesper"}} type MenuLocales = { readonly [Language in Locale]?: MenuTranslation } ``` The translations of a menu command, by language. ### MenuTranslation The translation of a menu command in one language: its name. **name** `string` The name shown in the menu in that language (1-32 characters). ## The limits What a file declares is checked when it loads, against the limits of Discord, with a message that says what to write: | What | Limit | | - | - | | A name (command, option, translated name) | Lowercase letters, digits, `-` and `_`, 32 characters at most | | A description (command, option, translated description) | 1 to 100 characters | | Depth of a command | A command, a group and a subcommand: 3 words at most in `name` | | Options of a command | 25 at most | | Choices of an option | 1 to 25, each shown as 1 to 100 characters, none twice | | `minLength`, `maxLength` | Whole numbers between 0 and 6000, `minLength` not above `maxLength` | | `min`, `max` | `min` not above `max`; whole numbers for an `'integer'` option | | The translated names of the options | No two options with the same name in one language | | `cooldown` | A duration of 1 second at least; no `guild` for a command with `where: 'dm'` | | `autocomplete` | A function per option, for a `string`, `integer` or `number` option without `choices` | | The name of a menu command (and its translations) | 1 to 32 characters, capitals and spaces allowed, no space at either end | | Menu commands | 15 used on a message and 15 used on a person; a slash command, a message menu and a user menu may share a name | | The suggestions (checked when sent) | 25 at most (the first ones are kept), each shown as 1 to 100 characters (cut beyond), a text value of 100 characters at most, a number for a number option, whole for an `'integer'` one | [Discord documentation](https://docs.discord.com/developers/interactions/application-commands#application-command-object-application-command-naming) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.