Custom Commands (CustomCmd)

Admins can define custom slash commands via /cc add. Users invoke them with /cmd <name> — autocomplete lists all available commands.

---

Activation

In configs/config.yml:

addons:
  customcmd: true

No YAML — custom commands are stored in the database (CustomCommand table). /cc add/edit/delete are the only interface.

---

Three Command Types

text

Plain-text response with placeholder support.

/cc add name: rules type: text response: "%user_mention%, please read the rules in #rules!"

Placeholder	Replaced with
%user_mention%	<@USER_ID>
%user_name%	Display name of the user
%user_id%	User ID
%guild_name%	Server name

embed

JSON-defined embed. Only title, description, and color are extracted from the JSON — all other fields are ignored (security constraint).

/cc add name: discord type: embed response: '{"title":"Discord","description":"We are here!","color":"#5865F2"}'

role-toggle

Toggles a role on the invoking user. response is the role ID.

/cc add name: notify type: role-toggle response: "1234567890123456" description: "Toggle notify pings"

User without the role → receives it. User with the role → loses it.

---

Commands

For Users

Command	Function
/cmd <name>	Execute a command. Autocomplete suggests names + descriptions — commands with allowed-role that the user doesn't have are hidden in autocomplete.
/cc list	Show all custom commands (long lists are truncated line by line and appended with …and N more)
/cc info <name>	Details (type, response, description, allowed role)

For Admins (Manage Guild)

Command	Function
/cc add <name> <type> <response> [description] [allowed-role]	Create a new command
/cc edit <name> [response] [description] [allowed-role] [clear-permissions]	Edit an existing command
/cc delete <name>	Delete a command

---

Name Validation

• Allowed: lowercase a-z, digits 0-9, _, -
• Max 32 characters
• Unique per server (duplicate → P2002 error with a friendly message)
• Anti-spoofing sanitization: name and description are automatically stripped of RTL-override and zero-width characters before being saved — prevents spoofing tricks (e.g. admin rendered backwards)

---

Security

Role-toggle is a direct privilege escalation vector — the bot takes this seriously.

Blocked Role Permissions

A role cannot be set up as a role-toggle if it has any of the following permissions:

Administrator
ManageGuild
ManageRoles
ManageChannels
ManageWebhooks
BanMembers
KickMembers
ModerateMembers
ManageMessages
MentionEveryone

Hierarchy Check

When running /cc add, the target role must be below the highest role of the creator. Otherwise, non-owner admins could create commands that elevate users above themselves.

role.managed blocked

Bot and integration roles (managed by Discord) cannot be toggled.

Defense in Depth

The permission check runs twice:

1. On /cc add — the command is rejected if the role is dangerous.
2. On /cmd <name> — checked again on every invocation. If someone later grants the role manager permissions, the toggle still refuses.

Mention Safety

All replies use allowedMentions: { parse: [] } — no @everyone/@here possible, even if an admin included them in the response.

Code Block Sanitization

/cc info displays the response. Backticks inside it are neutralized with zero-width spaces, so code blocks cannot break out of the display format.

---

Per-Command Restriction

Use allowed-role to restrict a command to users with a specific role:

/cc add name: vipchat type: text response: "Welcome to VIP!" allowed-role: @VIP

Invocation by a user without @VIP → ephemeral rejection.

/cc edit name: vipchat clear-permissions: true removes the restriction.

⚠️ Using clear-permissions: true together with allowed-role in a single /cc edit is rejected with a clear error message — the two options contradict each other, and the bot asks you to pick just one.

---

Rate Limits / Race Conditions

• Duplicate name → friendly P2002 message
• All write commands are transactional — no partially-created state

---

Examples

Server FAQ

/cc add name: ip type: text response: "Server IP: play.example.com (1.21.x)"
/cc add name: discord type: text response: "https://discord.gg/example"
/cc add name: shop type: text response: "https://shop.example.com"

Self-Assign Role

/cc add name: announcements type: role-toggle response: "ANNOUNCEMENT_ROLE_ID" description: "Pings for updates"

User runs /cmd announcements → role is added/removed.

Embed with Color Code

/cc add name: rules type: embed response: '{"title":"📜 Rules","description":"1. Be nice\n2. No spam\n3. See #rules for the rest","color":"#FFA500"}'