Commands runtime

Bot operation, messages and timers

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.

On this page

act · addtimer · alias · debug · die · dump · echo · exec · lastcom · msg · nick · rehash · remtimer · say · status · timers · update

act

Send an IRC action to a channel through the bot.

Access: Administrator+. IRC surfaces: channel + private message.

!act #channel <text>

Required channel is the destination; remaining text is an IRC CTCP ACTION (/me).

addtimer

Add a bot timer.

Access: Owner. IRC surfaces: channel + private message.

!addtimer <name> <seconds> <raw IRC command>

A named repeating bot timer. Interval is seconds; the payload is a raw IRC command, not automatically a Mediabot command or shell command. Inspect with timers and remove by name.

alias

Create or manage IRC command aliases (alias list, alias del ).

Access: Owner. IRC surfaces: channel.

!alias <alias> <command>
!alias list
!alias del <alias>

Legacy alias table: names use ASCII letters/digits/underscore/hyphen. Alias length 1–32, target length 1–64. This is separate from Unicode PUBLIC_COMMANDS templates.

debug

Change or display debug verbosity.

Access: Owner. IRC surfaces: channel + private message.

!debug [0..5]

No argument reads current verbosity. 0 is INFO; 1–5 enable increasing debug detail. The change is runtime state.

die

Ask the bot to quit.

Access: Master+. IRC surfaces: channel + private message.

!die [reason]

Optional reason defaults to bye. Requests a final shutdown. With the update-safe systemd template, exit 75 prevents automatic resurrection by Restart=always.

dump

Send a raw IRC command from the private command surface.

Access: Owner. IRC surfaces: private message.

/msg BotNick dump <raw IRC command>

Private-message surface only. Sends a raw IRC command through the IRC object; this is not a read-only internal state dump.

echo

Echo text for debugging.

Access: Public (legacy help says admin). IRC surfaces: channel + private message.

!echo <text>

Echoes the remaining text in the invocation context; empty text is silent. The helper has no explicit role gate despite the legacy admin help label.

exec

Execute a shell command. Dangerous and admin-only.

Access: Owner. IRC surfaces: channel.

!exec <command>

Runs the joined shell command in a bounded worker as the bot’s Unix user. Input max 512 characters; timeout is configured (default 8s, bounded 1–30s); up to three sanitized output lines. Refused dangerous patterns are not a general sandbox.

lastcom

Show recent command usage.

Access: Master+. IRC surfaces: channel + private message.

!lastcom [count]

Shows recent recorded command activity. Count defaults to the configured command-log limit and is capped by that limit; it is not a nick filter.

msg

Send a message through the bot.

Access: Administrator+. IRC surfaces: channel + private message.

!msg <nick|#channel> <text>

Required target is a nick or channel; remaining text is the message.

nick

Change the bot nickname.

Access: Owner. IRC surfaces: channel + private message.

!nick <newnick>

Changes the IRC bot nick; it does not rename the Unix account, ZNC user or NickServ account.

rehash

Reload bot configuration.

Access: Master+. IRC surfaces: channel + private message.

!rehash

Reloads bot configuration; it does not replace already-loaded Perl code. Use the service/update workflow for code changes.

remtimer

Remove a bot timer.

Access: Owner. IRC surfaces: channel + private message.

!remtimer <name>

Removes the named bot timer; it does not cancel every scheduled feature.

say

Send a channel message through the bot.

Access: Administrator+. IRC surfaces: channel + private message.

!say #channel <text>

Required channel is the destination; remaining text is sent as a channel message.

status

Show bot runtime status.

Access: Master+. IRC surfaces: channel + private message.

!status

No command parameters. Channel-scoped results refer to the invocation channel.

timers

List bot timers.

Access: Owner. IRC surfaces: channel + private message.

!timers

No command parameters. Channel-scoped results refer to the invocation channel.

update

Check GitHub, show durable local updater status, or install a newer release with 'now'. Master+.

Access: Master+. IRC surfaces: channel + private message.

!update [check|status|now]

Omission/check inspects the published source; status reads durable local updater status; now stages and installs an eligible newer version through the configured updater. A source or wiki edit is not deployed merely by changing a file.

Complete index · Command notation