> ## Documentation Index
> Fetch the complete documentation index at: https://kaoribot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Commands

> Create dynamic slash commands with custom responses and actions.

Custom Commands allow you to extend Kaori's functionality by creating your own slash commands. You can define triggers, responses (including rich embeds), argument options, and powerful actions like assigning roles.

# Creating a Command

1. Go to your server's **Dashboard**.
2. Navigate to **Custom Commands** in the sidebar.
3. Click the **New Command** button.

## Configuration Tabs

The editor is split into several tabs to help you organize your command's logic.

### General

* **Enable Command**: Toggle the command on or off instantly.
* **Name**: The name used to trigger the command (e.g., `welcome` becomes `/welcome`). Must be lowercase and no spaces.
* **Description**: A short help text shown in Discord's command picker.
* **Cooldown**: Minimum time (in seconds) a user must wait before using the command again.
* **Ephemeral**: If enabled, only the user running the command will see the response.

### Response

Define what the bot should say when the command is run.

* **Message Content**: Simple text response. Supports [Variables](#variables).
* **Embed**: Create a rich embed with title, description, color, fields, and images.

### Options (Arguments)

Add arguments to your command to make it dynamic. For example, a `user` argument lets you target a specific member.

|      Type      |        Description       |
| :------------: | :----------------------: |
|    **Text**    |   Simple string input.   |
|   **Integer**  |      Whole numbers.      |
| **True/False** |      Boolean toggle.     |
|    **User**    |  Select a server member. |
|   **Channel**  | Select a server channel. |
|    **Role**    |   Select a server role.  |

**Example**:

Create an option named `target` of type `User`. You can then use `{option:target}` in your response to mention them.

### Actions

Perform server actions when the command is executed.

* **Add Roles**: Assign specific roles to the user.
* **Remove Roles**: Remove specific roles from the user.
* **Send DM**: Send the response to the user's Direct Messages instead of the channel.

<Info>
  More Actions will be added with the future updates!
</Info>

### Permissions

Control who can use the command and where.

* **Allowed Roles**: Whitelist specific roles (only they can use it).
* **Denied Roles**: Blacklist specific roles (they cannot use it).
* **Allowed/Denied Channels**: Restrict usage to specific channels.

## Variables

You can use these placeholders in your Message Content and Embed fields. They will be replaced automatically.

|      Variable     |                         Description                        |
| :---------------: | :--------------------------------------------------------: |
|      `{user}`     |           Mentions the user who ran the command.           |
|    `{user.tag}`   |       The user's Discord handle (e.g., `User#1234`).       |
|    `{user.id}`    |                   The user's specific ID.                  |
| `{user.username}` |                    The user's username.                    |
|   `{guild.name}`  |                   The name of the server.                  |
|    `{guild.id}`   |                    The ID of the server.                   |
|    `{channel}`    |                Mentions the current channel.               |
|  `{channel.name}` |              The name of the current channel.              |
|  `{option:name}`  | The value of an argument option (e.g., `{option:target}`). |

### Example: Welcome Command

**Goal**: Create a command `/greet` that mentions a user and gives them a role.

1. **General**: Name = `greet`.
2. **Options**: Add option `target` (Type: User).
3. **Response**: "Hello `{option:target}`! Welcome to `{guild.name}`, invoked by user."
4. **Actions**: Add Role "Member".

**Usage**:

User types: `/greet target:@NewUser`

Bot responds: "Hello @NewUser! Welcome to MyServer, invoked by @Admin."

(And @Admin receives the "Member" role if configured, or @NewUser if the action logic targets the invoker - *Note: Current implementation targets the executor*).

## Advanced Mode (TagScript)

For power users, **Advanced Mode** unlocks a full code editor using [TagScript](https://npmx.dev/package/tagscript) (powered by the `tagscript` engine). This allows for conditional logic, randomness, math, and complex embed building.

### Enabling Advanced Mode

1. In the **General** tab of the command editor, toggle **Advanced Mode**.
2. A new **Code (TagScript)** tab will appear, replacing the Response and Actions tabs.

### Scripting Features

#### Variables

All standard variables (`{user}`, `{channel}`, etc.) work here. Additionally:

* **Arguments**: Use `{args}` to get all user-provided arguments joined together.
* **Specific Options**: Use `{option_name}` (without the `option:` prefix used in simple mode) to access specific argument values.

#### Logic & Control Flow

* **If Statements**: Check conditions.

  ```
  {if({args}==):You didn't say anything!|You said: {args}}
  ```
* **Random**: Generate random numbers or pick random items.

  ```
  Your lucky number is {random:1,100}
  I choose: {5050:Heads|Tails}
  ```

#### Embed Builder

You can build embeds directly in the script using `{embed}` tags.

```ts-tags lines theme={null}
{embed(title):My Embed Title}
{embed(description):This is a description with {user.mention}}
{embed(color):#5865F2}
{embed(field):Field Name|Field Value|true}
```

### Complete Example

Here is a "Magic 8-Ball" command script:

```ts-tags lines theme={null}
{if({args}==):You need to ask a question!|
  {embed(title):Magic 8-Ball 🎱}
  {embed(desc):Question: {args}}
  {embed(field):Answer|{5050:Yes, absolutely!|My sources say no.|Ask again later.}|false}
  {embed(color):#5865F2}
  {embed(footer):Asked by {user.tag}}
}
```