Repository navigation
Commands custom
Reviewed against Mediabot 3.6dev-20261006_084503 (snapshot of 6 October 2026). This is the development-line reference; consult the tagged source for stable-release behaviour.
Examples use !; replace it with the configured trigger (m, #, etc.). See notation, transport and permissions. Each entry names its registered IRC surfaces; a handler accepting a private context does not itself make a name callable by PM. Plugin and dynamic-command policy may add restrictions.
addcatcmd · addcmd · addresponder · chcatcmd · chowncmd · cmdvars · countcmd · delresponder · holdcmd · lastcmd · modcmd · mvcmd · owncmd · popcmd · remcmd · searchcmd · showcmd · showcommands · testcmd · topcmd
Create a PUBLIC_COMMANDS category.
Access: Administrator+. IRC surfaces: channel + private message.
!addcatcmd <category>
Category is one Unicode token, at most 64 characters.
Create a Unicode dynamic command; cmdvars lists template variables.
Access: Administrator+. IRC surfaces: channel + private message.
!addcmd <command> <message|action> <category> <text>
Required order is command, message/action, category, text. Category must already exist. Unicode name and template limits, variables and random choices are detailed below.
Add an automatic responder.
Access: Master+. IRC surfaces: channel.
!addresponder [#channel] <chance> <trigger> | <answer>
Chance is an integer 0–100 percent. Split trigger and answer with a literal |; both may contain spaces. Channel invocation defaults to that channel. In PM without a channel this creates a global responder.
Move a dynamic command to another category.
Access: Administrator+. IRC surfaces: channel + private message.
!chcatcmd <new_category> <command>
Category-first order is intentional: !chcatcmd general café.
Change the owner of a dynamic PUBLIC_COMMANDS command, including system-owned commands.
Access: Master+. IRC surfaces: channel + private message.
!chowncmd <command> <username>
Transfers ownership to an existing Mediabot handle; system-owned commands can be transferred.
List dynamic template variables, random choices and Unicode naming rules.
Access: public. IRC surfaces: channel + private message.
!cmdvars
Sends the variable/random-choice/Unicode naming reference privately by NOTICE. See the full template reference below.
Count dynamic PUBLIC_COMMANDS entries.
Access: Public read (legacy help says authorized). IRC surfaces: channel + private message.
!countcmd
No command parameters. Channel-scoped results refer to the invocation channel.
Remove an automatic responder.
Access: Master+. IRC surfaces: channel.
!delresponder [#channel] <trigger...>
Removes the whole trigger text in the selected scope; channel invocation defaults to that channel, PM without one is global.
Hold (on), reactivate (off) or toggle a dynamic command; default on.
Access: Administrator+. IRC surfaces: channel + private message.
!holdcmd <command> [on|off|toggle]
on disables the command; off reactivates; toggle reverses status. Omitted option means on. This does not delete the template.
Show the ten most recently created dynamic commands.
Access: Public read (legacy help says authorized). IRC surfaces: channel + private message.
!lastcmd
Shows the ten newest stored commands by creation date, not recently executed commands. A limit argument is not implemented.
Modify a validated dynamic template; owner or Master+ required.
Access: Administrator+ and owner of command, or Master+. IRC surfaces: channel + private message.
!modcmd <command> <message|action> <category> <text>
Same four-argument structure as addcmd; supply the full replacement template. Administrator plus ownership, or Master+, is required.
Rename a dynamic PUBLIC_COMMANDS command.
Access: Master+. IRC surfaces: channel + private message.
!mvcmd <old> <new>
Renames a dynamic command after Unicode, duplicate and reserved-name checks.
List dynamic-command owners and their command counts.
Access: Public read (legacy help says authorized). IRC surfaces: channel + private message.
!owncmd
Lists command owners and counts (up to 50), with bounded pagination. It does not take an owner filter. For one handle’s popular commands use popcmd <handle>.
Show popular dynamic commands.
Access: Public read (legacy help says authorized). IRC surfaces: channel + private message.
!popcmd <handle>
The handle is required. Returns that owner’s commands in popularity order with bounded pagination.
Remove a dynamic PUBLIC_COMMANDS command.
Access: Administrator+ and owner of command, or Master+. IRC surfaces: channel + private message.
!remcmd <command>
Removes a dynamic command, subject to ownership. Built-ins and plugin commands are not deleted by this path.
Search dynamic PUBLIC_COMMANDS entries.
Access: public. IRC surfaces: channel + private message.
!searchcmd <text...> [limit]
Literal search in command names and templates. Numeric final argument: default 5, clamped 1–20. It is a plain positional number: !searchcmd coffee 10, not literal limit=10.
Display a dynamic PUBLIC_COMMANDS command.
Access: public. IRC surfaces: channel + private message.
!showcmd <command>
Shows raw template, owner, category, hits, creation date and hold status. It does not execute the template.
List commands available for your level on a channel.
Access: public. IRC surfaces: channel + private message.
!showcommands [#channel]
Preview a dynamic command privately, including held commands; does not change hits.
Access: Administrator+. IRC surfaces: channel + private message.
!testcmd <command> [arguments]
Arguments are passed to the template as if invoked. The preview is private, including held commands; no hit increment or DB mutation. In PM %channel% is empty and random member falls back to caller.
Show most used dynamic commands.
Access: Public read (legacy help says authorized). IRC surfaces: channel + private message.
!topcmd
No command parameters. Channel-scoped results refer to the invocation channel.
Complete index · Command notation
| Variable | Meaning |
|---|---|
%n |
All arguments joined by spaces; caller's nick when there are none (legacy behaviour) |
%N, %nick%
|
Caller, even when arguments are supplied |
%target% |
First argument, or caller if absent |
%args% |
All arguments, or empty text if absent |
%1 … %9
|
Individual argument; empty if missing |
%c, %channel%
|
Invocation channel |
%command% |
Command name |
%s |
Command name with _ replaced by spaces |
%r, %R
|
Random member of the invocation channel; caller if unavailable |
%date%, %time%
|
Bot's local date (YYYY-MM-DD) and time (HH:MM) |
%yesno%, %on
|
Random oui or non
|
%bool%, %b, %B
|
Random true or false
|
%rand{min,max}, %random{min,max}
|
Random integer with both bounds included |
%choose{a|b|c}, %choice{a|b|c}
|
One literal option |
%d, %dd, %ddd
|
Legacy ranges 1–10, 10–99, 100–999 |
%% |
A literal percent sign; %%n prints %n
|
Random bounds must be integers satisfying
-1000000 <= min <= max <= 1000000. Equal bounds are allowed. Choices require
2–20 non-empty options. Inside a choice, escape literal delimiters with
\|, \{, \} and \\. For example %choose{a\|b|c} chooses a|b or c.
A draw works immediately before punctuation, e.g. %rand{1,6}! or %d!.
Each occurrence of the explicit %rand{...}, %choose{...}, %yesno% and
%bool% variables draws independently. Repeated legacy %on, %b, %B,
%r or %R reuse their respective first value within one invocation.
Legacy numeric variables still draw independently.
Values are inserted once. Arguments, nicknames and choice values cannot
introduce another template expansion. %choose{bonjour %n|salut %n} therefore
contains literal %n; instead use %choose{bonjour|salut} %n.
Nested choices and expressions are unsupported. There is no Perl, shell or
arithmetic evaluation; unknown named placeholders such as %unknown% remain
literal. Rendered output is capped at 4096 characters, then follows the normal
IRC sender's UTF-8 splitting, channel settings and flood handling.
!addcatcmd general
!addcmd café message general %choose{bonjour|salut} %nick% ☕
!modcmd café message general %choose{tea|coffee} for %target%
!testcmd café Alice
!searchcmd coffee 10
Command name: one NFC-normalized Unicode token, at most 64 characters. First character: Unicode letter, decimal digit, _ or -; later characters also permit combining marks. Category is an existing normalized token (max 64). Built-in/plugin names are reserved under the matching folded form; duplicate names are refused. Database collation also determines case/accent equivalence. Type is message or action. Template text is nonempty, max 244 Unicode characters; malformed random variables and CR/LF/NUL/CTCP delimiters are rejected before a write. These are template limits, distinct from the expanded 4096-character rendering cap.
Mediabot v3 documentation · Home · Installation · Commands · Troubleshooting · GitHub
- Start: notation and parameters
- Public commands
- Complete command reference
- Private and admin commands
- News and RSS
- Quotes and automatic quotes
- Dynamic commands
- AI and Hailo
- Access levels
- Chansets