BlackTools Documentation
The Ultimate Channel Control Script — One TCL. One smart Eggdrop.
A complete reference for every command, protection and module.
#Overview
BlackTools is a complete channel-management script for Eggdrop bots. It bundles ~70 commands, 25+ protections (flood, spam, advert, badword, clone detection…) and 25+ modules (seen, quotes, notes, greets, topic control, X integration…) into one package. Every channel can be configured independently — each owner/manager toggles the protections, modules and commands they want.
| Script | BlackTools v2.5.5 (GitHub master, 2021) |
|---|---|
| Author | Daniel Voipan (BLaCkShaDoW) — www.tclscripts.net |
| Requirements | Eggdrop 1.8.x or newer · Tcl 8.5 or newer |
| Languages | English · Romanian · Spanish · French (lang files auto-loaded from lang/) |
| Home channel | Set via black(homechan) in BlackTools.tcl (default: none) |
| Network services | Undernet X (x@channels.undernet.org) — auto-login supported |
| Online help | #TCL-HELP on Undernet · GitHub |
!h shows every command available
to you at your access level, and !man <command> shows the built-in manual page for any
command, protection or module. When in doubt — !man it.#What's new in 2.5.5
Summary of the changes between v2.5.3 (2018) and v2.5.5 (GitHub master, 2021),
compiled from the shipped ChangeLog and a comparison of the sources.
New modules & protections
| Feature | Description |
|---|---|
AutoUpdate | The bot updates itself from GitHub when a new BT version or bugfix is released — on a timer or by command (!update). All BT files and your BlackTools.tcl settings are backed up and restored. Powered by the new Addons/ folder (http, json, github helper libraries) — no external TLS package needed. Can auto-restart the bot when an update requires it. |
Alias | Users can build their own personalized commands on top of BT commands, with %1%/%2% argument placeholders. |
Vote | Full channel voting system: open votings with multiple options, expiry times, access-only or everyone participation, and result listings. |
NoProxy | New protection that bans users joining from IPs identified as proxies. The ban reason supports an %isp% placeholder. |
AntiBotIdle | New egg setting that keeps the eggdrop itself from idling on the server. |
| ChanServ mass-ban detector | The bot detects mass-bans done through X and suspends the abuser (configurable coverage percent, suspend level and time). |
Regex ban system
The ban engine (rewritten in the new BT.Ban.tcl, faster) now supports
regular-expression bans: !b -regex,
!ub -regex, !sb -regex and !banlist regex. Regexes match against
nick!ident@host/[realname]/[banmask type]. The BadChan module also accepts regex badchans
(!badchan regex <#regex>) and got a faster, safer scanning mode.
Other changes
| Change | Detail |
|---|---|
| DCC party-line support | All commands now work through DCC chat: .bt <command> [#channel] [arguments] (with !myset mychan set, the channel can be omitted). |
| Languages | Spanish translation added; French language files are also shipped. |
| GuestNick removed | The GuestNick module was removed in the 2021-03-15 update. |
| Quote access control | New quote:usage setting: choose whether only users with access, or everyone, may add/list/remove quotes. |
| AntiColor tuning | New option to punish only specific colour codes (anticolor:specific_colors). |
| DNS on-join toggle | black(dns_onjoin) lets you disable DNS lookups on join (faster on big channels). |
| Flood action change | The private-message antiflood action changed from server SILENCE to IGNORE. |
| Fixes | Gag durations for all access levels, TopWords now counts all users, NickServ login, clonescan bans, Idle module vs. SecureMode +mD interaction, alias/notes/suspends cleaned up when users expire, and assorted minor bugs. |
#Installation
From the INSTALL file — how to get BlackTools running on a fresh eggdrop.
# 1. get the latest version (or unpack the release archive) git clone https://github.com/tclscripts/BlackToolS-TCL # 2. edit BlackTools.tcl to your liking (homechan, cmdchar, X login, defaults…) # 3. copy everything into your eggdrop's scripts/ directory (case sensitive!) cp -r BlackTools/ /home/of/your_eggdrop/scripts/ cp BlackTools.tcl /home/of/your_eggdrop/scripts/ # 4. add this line at the END of your eggdrop config file source scripts/BlackTools.tcl # 5. restart the eggdrop, then in any channel type: .h
The directory layout that must live under scripts/:
#Using the bot
Every BlackTools command can be triggered four ways. All examples in
this documentation use !, but the bot answers to any of the configured trigger characters
(stock: ! . ` ^ — change them with
set cmdchar) — plus the botnick prefix, private message, and (new in 2.5.5) DCC chat.
!command <args> # trigger char, in the channel BotNick command <args> # address the bot by nick, in the channel /msg BotNick command #channel <args> # private message — add the #channel .bt command [#channel] <args> # DCC party-line (channel optional with myset mychan)
<required> arguments are mandatory,
[optional] arguments may be omitted. [#chan] is only needed when messaging the bot
privately or acting on another channel. Durations are written 10m (minutes), 3h
(hours), 2d (days) — and 0 means permanent.The help menu
!h
Any accessThe most important command. Shows all commands available at your access level, plus category submenus. Disabled commands are hidden or greyed out.
!h [category] # categories: cmds · ban · add · manager · master · owner # btinfo · chaninfo · module · egg
!h # your main menu !h ban # every kick/ban command you can use !h module # which modules are ON (+) or OFF (-) on #channel !h chaninfo # channel flags & eggdrop flood settings /msg BotNick h #channel ban
!man
Any accessThe built-in user manual. Displays usage information for every command, protection and module — the same content as this page, live on IRC.
!man <command>
!man b # manual for the ban command !man antipub # manual for the anti-advertising protection !man banmethod # explains the 7 punishment methods
#Access levels
BlackTools layers its own named levels on top of eggdrop flags. Channel levels apply per-channel; global levels apply bot-wide. Each level inherits everything below it.
| Level | Scope | Eggdrop flag | Typical powers |
|---|---|---|---|
| Voice | channel | |V | voice self, seen, invite, kick/warn, myset, h/man |
| Op | channel | |O | + op/deop, modes, topic, cycle, most ban commands |
| Admin | channel | |A | + say/act, add users, suspend, black/stick bans, stats |
| Manager | channel | |M | + set/unset channel settings, enable/disable commands, exempt, purge, del/chuser |
| Master | global | o | manager powers on every channel + addchan/delchan, suspend chans, status |
| Owner | global | m | + global bans, broadcast, die/restart/jump, cp, TCL loading |
| Boss owner | global | n | everything, incl. editing eggdrop.conf settings from IRC (egg) |
!set +oprotect / +vprotect / +hoprotect.#General commands
Everyday commands available from the lowest access level upward.
!version
Any accessDisplays the BlackTools version the eggdrop is running.
!version!i / !invite
Voice+Invites a user to the channel. The bot must be opped (@) for the invite to work.
!i <nick> # in channel /msg BotNick i #channel <nick>
!i JohnDoe # invite JohnDoe to #channel
!seen
Voice+Searches the per-channel seen database for a nick, IP or host (wildcards supported). Shows when the
person was last seen and what they did. Owners+ can search global across all channels.
Flood-protected (2 searches / 20s by default).
!seen <nick|ip|host> !seen global <nick|ip|host> # owners+ — all channels
!seen JohnDoe !seen *!*@*.videotron.ca
Related: +seen module toggle · +seenlastmsg (show last message) ·
+seenreply (notify people they were searched for)
!activ
Voice+Shows the last recorded channel activity of a user (last join, part, kick, ban, text…), pulled from the bot's action tracker.
!activ <nick>
!for
Voice+Makes multiple eggdrops (all running BlackTools) execute the same command simultaneously — handy when several bots guard the channel.
for <botnick1>,<botnick2>.. <command> [option]
for Bot1,Bot2 say Good morning everyone!!info
Admin+Displays database information about a user or a channel: access level, added hostmasks, automode, greet line, last-seen info, channel topic/URL/manager, and more.
!info <handle|#chan>
!info JohnDoe !info #channel
!addinfo
Voice+Sets a personalised greeting line for yourself, shown in !info and announced by the bot
when you join (requires +greet on the channel). Same as !myset greet.
!addinfo <text|reset>
!addinfo Hello everyone, glad to be here!#Channel op commands
Op/voice management, modes, topic and channel messages.
!v
Voice+Gives or removes voice (+v) for one or more users. With no nick, voices you (if you aren't voiced already).
!v [nick1] [nick2].. !v + # mass voice everyone !v - # mass devoice
!v JohnDoe JaneDoe!o
Op+Gives or removes op (@) for one or more users. With no nick, ops you.
!o [nick1] [nick2].. !o + # mass op !o - # mass deop
!ho
Op+Gives or removes halfop (+h %) for the specified users. !ho + /
!ho - perform a mass halfop / dehalfop.
!ho [nick1] [nick2]..
!mode
Op+Applies or removes channel modes.
!mode <+/-modes>
!mode +m # moderate the channel !mode -m+ntr
!t
Op+Sets the channel topic. With !set +showhandle, the bot appends the handle of whoever
changed it.
!t <text>
!t Welcome to #Channel — read the rules and have fun!!r
Op+Manually refreshes/re-applies the stored channel topic (see also the +refresh and
+autotopic settings).
!r [#chan]
!cycle
Op+Makes the bot cycle (part and re-join) the channel, optionally waiting a given duration.
!cycle [duration|reason]
!omsg
Op+Sends a message to all users with op (@) on the channel — or on every channel with
all.
!omsg <#chan|all> <text>
!omsg #channel Watch for the spambot wave, set +m if it gets bad!say
Admin+Makes the bot say a message to the channel.
!say [#chan] <message>
!say Quiz night starts in 10 minutes!!act
Admin+Makes the bot send an action (/me) to the channel.
!act [#chan] <message>
!act waves at everyone!msg
Owner+Sends a message to any target — a channel, a nick (query) or a chat window.
!msg [target] <message>
!broadcast
Owner+Sends a message to all channels the bot is in.
!broadcast <message>
!check
Op+Sends a private verification message to a user — used to test whether they are infected/advertising (drones often auto-reply). The message text is configurable.
!check <nick>
Optional settings: check-message (default check text)
#Kick & ban commands
The heart of BlackTools: a full ban system with per-ban levels, durations, sticky
bans, global bans, comments and searchable banlists. Durations: minutes /
hours / days, 0 = permanent. Most commands accept a nick
or a mask — if the nick isn't on the channel, the bot will WHOIS it.
!k
Voice+Kicks a user (or everyone matching a mask) from the channel.
!k <nick|mask> [reason]
!k Troublemaker !k Troublemaker Please keep it civil
Optional settings: k-reason (default kick reason)
!w
Voice+Delivers a warning kick — a kick with a configurable warning reason and message.
!w <nick>
Optional settings: w-reason · w-message
!b
Op+The main ban command. Bans a nick or mask for a duration (stock default: 2 days).
A duration of 0 makes the ban permanent (blacklisted). -level protects the
ban from removal by lower access. Owners+ can add global (all channels) or
link (linked channels). -c comment attaches a note visible on the ban entry.
Supports CIDR masks like *!*@192.168.0.1/17 — and, new in 2.5.5,
regex bans with -regex, matched against
nick!ident@host/[realname]/[banmask type] (bracketed fields optional).
!b [-regex] <nick|mask|regex> [-level] [duration] [reason] [-c comment] !b [-regex] <nick|mask|regex> [-level] [duration] [global|link] [reason] # owner+
!b SpamGuy 2d advertising !b *!*@198.51.100.* 12h botnet range !b Griefer -400 0 permanent, level 400 protection !b Flooder 3d flooding -c third offence this week !b -regex [a-z]+[0-9][0-9]!*@* 1d drone pattern
Optional settings: b-reason · b-bantime (default 2d) ·
b-banmask (default *!*@host)
!ub
Op+Removes a ban by nick, mask or ban ID (wildcards supported). If the nick isn't on channel the bot
WHOISes and unbans by ident/host/nick — matching regex bans are removed too. Use -regex
to remove a stored regex ban directly. Careful: !ub * removes
all channel bans.
!ub [-regex] <nick|mask|id|regex> [global|link]
!ub SpamGuy !ub 1234 # by ban ID (see +showid / !sb)
!sb
Op+Searches the banlist and shows full details of a ban — who set it, when, why, expiry, comment.
Also matches and inspects regex bans (-regex).
!sb [-regex] <nick|mask|id|regex> [global]
!sb *!*@*.example.net!banlist
Op+Shows the active bans on the channel — all of them, only yours, other people's, regex bans only,
gags only, or (owners+) the global list. Paged output; follow with -next for more
entries.
!banlist <all|handle|regex|gag|other> !banlist global # owner+
!black
Admin+Bans a user permanently (blacklist). Equivalent to !b ... 0.
!black <nick|mask> [reason] [-c comment]
!black KnownTroll repeat offender -c do not removeOptional settings: black-reason · black-banmask
!stick
Admin+Sets a sticky ban: if anyone removes it from the channel banlist, the bot puts it right back. Stock default duration: 2 days.
!stick <nick|mask> [duration] [reason] [-c comment]
Optional settings: stick-reason · stick-bantime · stick-banmask
!n
Op+Bans on the user's nickname (mask nick!*@*). Default: 2h.
!n <nick>
Optional settings: n-reason · n-bantime · n-banmask
!id
Op+Bans on the user's ident (mask *!user@*). Given a nick, the bot grabs
the ident automatically. Default: 2h.
!id <nick|ident>
Optional settings: id-reason · id-bantime · id-banmask
!mb
Op+Bans a nickname automatically on ident, with an optional reason. Default: 2d.
!mb <nick> [reason]
Optional settings: mb-reason · mb-bantime
!dr
Op+Bans with a default DRONE reason — for compromised clients/drones. Default: 15d.
!dr <nick|mask>
Optional settings: dr-reason · dr-bantime · dr-banmask
!vr
Op+Bans with a default VIRUS/TROJAN reason. Default: 3d.
!vr <nick|mask>
Optional settings: vr-reason · vr-bantime · vr-banmask
!bot
Op+Bans with a default BOT reason — for unauthorised bots. Default: 7d.
!bot <nick|mask>
Optional settings: bot-reason · bot-bantime · bot-banmask
!spam
Op+Bans with a default SPAM reason. Default: 7d.
!spam <nick|mask>
Optional settings: spam-reason · spam-bantime · spam-banmask
!bw
Op+Bans with a default bad word reason. Default: 1d.
!bw <nick|mask>
Optional settings: bw-reason · bw-bantime · bw-banmask
!troll
Op+Bans with a default TROLL reason. With +showtroll enabled, the bot
notices a "trolls of the day" list to access-holders when they join (reset at midnight).
!troll <nick>
Optional settings: troll-reason · +showtroll
!gag / !ungag
Op+Silences a user — they can't write on the channel — for a period (default: 10m). The bot re-bans
(+b with mute) if the gag is removed early. !ungag lifts it.
!gag <nick> [duration] [reason] !ungag <nick|mask>
!gag LoudGuy 30m take a breatherOptional settings: gag-reason · gag-bantime · gag-banmask
!exempt
Manager+Manages the ban-exempt list: hosts on it are never banned by the bot. Owners+ can make an exempt
global.
!exempt add <ip|host> [period] [global] [reason] !exempt list [global] !exempt del <ip|host> [global]
!exempt add *!*@trusted.users.undernet.org 0 our regular helper!stats
Admin+Shows ban/command statistics for a user. Managers+ can reset. Requires the
+banstats setting to collect data (see also !banstats total|reset).
!stats <handle> [total|reset]
!report
EveryoneLets regular users (and voice/protect) report a nickname for adverts or spam. The bot
relays the report to channel ops via @notice. Needs +reportnick and the bot opped.
Flood-limited (2 reports / 60s).
!report <nick> <comment>
!report LinkSpammer keeps pasting shady links in PM#User management
Adding people to the bot, hostmasks, automodes and suspensions. You can only act on users with access lower than your own.
!add
Admin+Adds a user to the channel's userlist at a given level (voice, op,
admin, manager…). If the user is on channel, their current hostmask is added
(default style: *!*@host). If not, the Undernet default is used:
*!*@<user>.users.undernet.org — so you can add people by X username.
!add <level> <nick|Xusername>
!add op JohnDoe # JohnDoe is on channel → current host added !add voice SomeUserX # not on channel → *!*@SomeUserX.users.undernet.org
!userlist
Admin+Shows the channel's access list, filtered by level or all of it.
!userlist <level|all> # levels: voice · op · admin · manager · owner · master
!userlist op!delacc
Admin+Removes a user's access from the channel (their record stays in the bot). Must target someone with
lower access than you. Owners can strip global owner|master access too.
!delacc <handle> !delacc <owner|master> <handle> # remove a global level
!del
Manager+Deletes a user entirely from the bot's database — all channels, all hosts.
!del <handle>
!auto
Admin+Sets a user's automode — the bot automatically ops or voices them on join. The user must already
have access on the channel. Owners+ can apply it -global.
!auto <+/-o> <nick|handle> [-global] # auto-op !auto <+/-v> <nick|handle> [-global] # auto-voice
!auto +v JohnDoe!s / !us
Admin+!s suspends a user's access on the channel for a period (default: 2d);
!us lifts the suspension. Only works downward in the hierarchy.
!s <handle> [duration] [reason] !us <handle>
!s RogueOp 3d abusing kick command!addhost / !delhost
Admin+Adds or removes a hostmask on a user's record.
!addhost <handle> <mask> !delhost <handle> <mask>
!addhost JohnDoe *!*@JohnDoe.users.undernet.org!chuser
Manager+Renames a user's handle in the bot's database.
!chuser <handle> <newhandle>
#Channel management
Settings, toggles and channel administration — the manager's toolbox.
!set
Manager+The universal switchboard. Turns protections/modules on or off (+flag /
-flag) and assigns values to string options. Owners+ can use global to apply a
setting to every channel. See the Protections and
Modules sections for every flag.
!set <+/-flag> # toggle !set <option> <value> # assign !set global <option> <value> # owner+ — all channels
!set +antipub # enable anti-advertising !set chanmode +ntk s3cret # enforce modes incl. a key !set b-bantime 4h # default !b duration → 4 hours !set url https://www.example.com
!unset
Manager+Resets a setting/option back to default. Owners+ can unset global.
!unset <flag|option> !unset global <flag|option>
!show
Manager+Shows the current value of any setting.
!show <setting>
!show antipub-bantime!enable / !disable
Manager+Enables/disables a command on the channel — for everyone or for a specific user. Masters+ can apply
it globally (commands only, not users). Disabled commands show greyed-out in
!h.
!disable <command|all> [user] [global] !enable <command|all> [user] [global]
!disable k TriggerHappyOp # take !k away from one user !enable all
!ignore
Manager+Adds, lists or removes bot-level ignores (default duration: 6h).
!ignore add <ip|mask> [duration] [reason] !ignore list !ignore del <ip|host>
!purge
Manager+Deletes the channel from the bot's channel database (manager-only variant of
delchan).
!purge <#chan> <reason>
!addchan / !delchan
Master+Adds a channel to the bot (it joins immediately; an optional key is used to get in) or removes one.
!addchan <#chan> [key] !delchan <#chan> <reason>
!suspend / !unsuspend
Master+Suspends a channel — the bot leaves and won't join or act in it — or reverses that.
!suspend <#chan> <reason> !unsuspend <#chan>
!channels
Master+Lists all channels the bot is joined to (channels flagged +invisible are hidden from
non-boss users).
!channels!cp
Owner+Copies configuration from one channel to another.
!cp <userlist|banlist|settings|badchans> <#chan1> <#chan2>
!cp settings #channel #channel-ops!link
Owner+ChanLink module — synchronises bans across two or more channels: a ban added on one linked channel is mirrored to the others (and removed everywhere on unban).
!link <#chan1> <#chan2> | all !link del <#chan> !link <list|reset> # then, ad hoc: !b <nick|mask> [duration] link [reason] !ub <nick|mask> link
#Bot owner commands
Bot lifecycle and shell-free administration. Boss owners can even edit
eggdrop.conf values straight from IRC — see Eggdrop.conf via IRC.
!uptime / !status
Master+!uptime shows how long the bot has been up, when it connected and to which server.
!status shows monitored channels, total users, version and bot owner.
!uptime !status
!die · !restart · !rehash · !save
Boss ownerdie shuts the bot down. restart restarts it as a background process
(use when lagged/malfunctioning). rehash reloads all files after user/channel record
changes. save writes the user/channel files to disk.
!die [reason] · !restart · !rehash · !save
!jump
Boss ownerMakes the bot connect to a different IRC server.
!jump [irc server]
!jump Ashburn.Va.Us.UnderNet.org!nick
Boss ownerChanges the bot's nickname. !set nick <newnick> makes it permanent (written to
the config).
!nick <newnick>
!login
Boss ownerManually logs the bot in to ChanServ (X on Undernet) using the configured
username/password. Auto-login is controlled by black(autologin) in
BlackTools.tcl.
!login!chat
Boss ownerConnects you to the bot's botnet/partyline — same as /CTCP BotNick CHAT.
!chat!tcl
Boss ownerManages Tcl scripts live: list, download from a URL (restricted to *.tcl), load,
unload, or inspect.
!tcl list !tcl wget <link/name.tcl> !tcl load <name.tcl> !tcl unload <name.tcl> !tcl info <name.tcl>
!timer
Boss ownerPRO module — start/stop internal process timers or list active ones. Do not touch unless you know exactly what you're doing.
!timer start <timer:setting> !timer kill <pid> !timer list
#Protections
Each protection is toggled per channel with !set +name /
!set -name and tuned via optional settings (name-reason,
name-bantime, name-banmethod, name-banmask…). Punishments follow
the ban-method scale (warn → kick → ban). The "defaults" line on each card shows
the stock values shipped in BlackTools.tcl. Users with
PROTECT level — and ops/voices when +oprotect/+vprotect is on —
are exempt.
AntiPub
Manager+ to configureBans users advertising channels/links (*#*, *www.*,
*http://*…). Wildcard word list with exceptions — YouTube links are excepted by
default.
!set +antipub !antipub add <link|#chan> # add pattern !antipub add +word # add exception !antipub list · !antipub del <no.>
Stock defaults: ban 2d · method 6 (kick→ban) · mask *!*@host ·
settings: antipub-reason/-bantime/-warn/-banmethod/-banmask
AntiNotice
Manager+ to configurePunishes users who send NOTICEs to the channel.
!set +antinoticeStock defaults: ban 2d · method 3 (ban) · mask *!*@host · sets channel mode
+mr for 45s during an attack
AntiCTCP
Manager+ to configurePunishes users who send CTCPs to the channel.
!set +antictcpStock defaults: ban 3d · method 3 (ban) · mask *!*@host · mode
+mC for 45s
AntiBadWord
Manager+ to configurePunishes use of forbidden words/phrases (wildcards). Words can carry their own punishment method:
word:6.
!set +antibadword !badword add <word|phrase> · !badword add <word:method> !badword add +word # exception · !badword list · del <no.>
Stock defaults: ban 6h · method 6 (kick→ban) · mask *!*@host
AntiLongText
Manager+ to configurePunishes messages that are too long (stock limit: 215 characters).
!set +antilongtextStock defaults: ban 30m · method 6 · mask *!*@host · setting
antilongtextmax
AntiBadQuitPart
Manager+ to configurePunishes forbidden words in part/quit messages. Extras: +quitpartcolor (colours in
quit/part) and +quitpartmsgflood (overlong quit/part messages, default 120 chars).
!set +badquitpart !badquitpart add <word> · add +word · list · del <no.>
Stock defaults: ban 1h · mask *!user@host
AntiSpam
Manager+ to configureBans users who private-spam channel members (patterns with # or *www.*).
The optional +spamjoinmessage extra sends a bait verification PM to every joiner —
spambots that reply get caught. Scan cycle: 60m.
!set +antispam !antispam add <*text*> · add +word · list · del <no.> !set +spamjoinmessage · !set antispam-message <text>
Stock defaults: ban 6d · mask *!*@host · settings:
antispam-scantime
AntiRepeat
Manager+ to configurePunishes repeating the same text (stock default: 3 repeats within 5s).
!set +antirepeatStock defaults: ban 10m · method 7 (warn→ban) · mask *!*@host · setting
antirepeat-setting (repeats:seconds)
AntiColor · AntiBold · AntiUnderline · AntiCaps
Manager+ to configureThe formatting police: punishes colours, bold, underline, or CAPS abuse (stock caps limit:
50 chars). Since 2.5.5, AntiColor can be limited to specific colour codes via
black(anticolor:specific_colors) in the config.
!set +anticolor · !set +antibold · !set +antiunderline · !set +anticaps
Stock defaults: ban 10m · method 7 (warn→ban) · mask *!*@host each
RepetitiveChars
Manager+ to configurePunishes consecutive repeated characters (stock default: 10 in a line — "aaaaaaaaaa").
!set +repetitivecharsStock defaults: ban 10m · method 7 · mask *!user@host · setting
repetitivechars-char
BadNick
Manager+ to configureBans nicknames containing forbidden words (checked on join and nick change). Method 1 warns first and gives 30s to change nick before banning.
!set +badnick !badnick add <word> · add +word · list · del <no.>
Stock defaults: ban 1h · mask nick!*@* · settings:
badnick-bmethod (1 = warn→ban, 2 = ban) · badnick-banwait (30s)
BadIdent
Manager+ to configureBans idents containing forbidden words (checked on join).
!set +badident !badident add <word> · add +word · list · del <no.>
Stock defaults: ban 1h · mask *!user@*
BadRealname
Manager+ to configureBans realnames containing forbidden words/links (checked on join).
!set +badrealname !badrealname add <word> · add +word · list · del <no.>
Stock defaults: ban 2h · mask *!*@host · default patterns include
*www.*, *#*, *http://*
BadHost
Manager+ to configureBans users whose IP/vhost contains forbidden words.
!set +badhost !badhost add <ip|mask> · add +word · list · del <no.>
Stock defaults: ban 3h · mask *!*@host
AntiJoinFlood
Manager+ to configureCounters mass-join floods: locks the channel (+mr here, 45s) and bans flooders. Also
catches join/part-quit cycling. Per-user limit here: 3 joins / 15s.
!set +antijoinflood !set joinflood <joins:seconds>
Stock defaults: ban 1h · mask *!*@host · see also
+antijoinpart
AntiChanFlood
Manager+ to configurePunishes text flooding (stock default: 4 lines / 5s). Locks the channel +mr for 45s
while it cleans up.
!set +antichanflood !set chanflood <lines:seconds>
Stock defaults: ban 10m · method 6 (kick→ban) · mask *!*@host
NickFlood
Manager+ to configurePunishes rapid nick-changing (stock default: 3 changes / 120s).
!set +nickfloodStock defaults: ban 10m · method 7 (warn→ban) · mask nick!user@host ·
setting nickflood-repeat
NoProxy NEW in 2.5.5
Manager+ to configureBans users joining from IPs identified as proxies. The ban reason supports the
%isp% placeholder, replaced with the IP's ISP name. An except-hosts list lives in the
config (black(noproxy:excepts)).
!set +noproxyStock defaults: ban 1h · settings: noproxy-reason ·
noproxy-bantime
InviteBan
Manager+ to configureBans users who try to invite the bot into unauthorised channels.
!set +invitebanStock defaults: ban 3h · mask *!*@host
AntiTake (dontop / dontdeop)
Manager+ to configureAnti-takeover. +dontdeop: unauthorised users who deop others get deopped, victims get
re-opped. +dontop: unauthorised users who op someone get both parties deopped.
!set +dontdeop !set +dontop
SecureMode
Manager+ to configureUndernet-specific botnet shield. Works with channel modes +Dm: each first-time joiner
receives a unique code to confirm before being let in. +strictsecured requires the code on
every join. Known-good hosts can be whitelisted.
!set +securemode !securemode add <ip|mask> · del <no.> · list !set +strictsecured
CloneScan
Manager+ to configurePeriodically scans for clones (multiple connections from one host) and bans them. Stock defaults: max 3 clones, scan every 45m, ban 180m.
!set +clonescan !clonescan add <ip|mask> # whitelist · del <no.> · list
Settings: clonescan-maxclone · clonescan-bantime ·
clonescan-reason · clonescan-scantime
BadChan
Manager+ to configureBans users who sit in forbidden channels (wardriving hack/warez/adult channels — a default list
ships in the config). Scans every 10m; method 1 warns and gives 30s to leave the bad channel first.
+showbadchan tells the ops which bad channel triggered it. Rewritten in 2.5.5 — faster
and safer — and now accepts regex badchans.
!badchan <ON|OFF> !badchan add <#badchan> [global] [reason] !badchan regex <#regex> [reason] # e.g. #[a-z]+[0-9][0-9] !badchan add +#chan # exception · list [-global] · del <no.>
Stock defaults: ban 6h · mask *!*@host · settings:
badchan-scantime · badchan-bmethod · badchan-banwait ·
badchan-floodcontrol (join-flood pause, 5:5)
#Modules
Feature modules, toggled per channel. Check what's enabled with
!h module — green [+] is on, red [−] is off.
XTools
Manager+Lets the bot ask Undernet's X for op, voice, invite, or to unban itself when it needs
help.
!set +xtoolsXOnly
Manager+Full channel administration through X: the bot performs all BlackTools commands via
X even when it isn't opped. X bans use their own level and duration.
!set +xonly !set xbantime <time> · !set xbanlevel <level>
Stock defaults: X ban time 1 · X ban level 100
Seen
Manager+Per-channel seen database powering the !seen command. Extras:
+seenlastmsg (include the person's last message) and +seenreply (tell users
who searched for them). Entries expire after 730 days.
!set +seen · !set +seenlastmsg · !set +seenreply
Greet & Leave
Manager+Channel welcome and goodbye messages. Greet supports the Count variables:
%nick%, %countchan%, %count% (join number),
%time%. Use ~ to split into multiple sentences.
!greet <ON|OFF> · !greet set <message> !leave <ON|OFF> · !leave set <message> !set greet-method <NOTICE|PRIVMSG> · !set leave-method <NOTICE|PRIVMSG>
!greet set Welcome to %countchan%, %nick%!~You are visitor number %count% since %time%Anunt (Advert)
Manager+Rotates announcements/ads on the channel — but only while the channel is active (no activity =
no ads). Supports %chan% and %botnick%, multi-sentence with
~.
!anunt <ON|OFF> !anunt add <text> · list · del <no.> !set anunt-showtime <period>
Stock interval: 52m
AutoBroadcast (bt)
Owner+Broadcasts stored messages, one at a time, across all channels. Channels flagged
+silent are skipped.
!bt <ON|OFF> !bt add <message> · list · del <no.> !set +silent # opt this channel out
Stock interval: 55m, sent as ACTION
Limit
Manager+Keeps the channel limit (+l) floating a few places above the current user count — an old-school anti-massjoin trick. Stock margin: 6.
!limit <ON|OFF> !limit set <number>
Topic · AutoTopic · Url
Manager+Stores the official channel topic and URL. +autotopic re-applies them whenever someone
changes the topic; +refresh re-applies on an interval; !r does it manually.
+showurl appends the URL to ban reasons.
!topic set <text> · !topic unset !set url <url> !set +autotopic · !set +refresh · !set +showurl
Idle (Anti-Idle)
Manager+De-ops/-voices/-halfops users who idle too long. Stock defaults: ops 10m, voices 30m, halfops 30m,
scanned every 5m. An exception list is available. Since 2.5.5 the module waits while the channel is
+mD under SecureMode.
!idle <+/-o | +/-v | +/-ho> !idle add <nick> · list · del <nick> !set idleopmax <period> · idlevoicemax · idlehalfopmax · idle-scantime
VoiceMe
Manager+Lets X-logged users voice themselves with /msg BotNick voiceme #channel. Extras:
+onlyonmode restricts it to when the channel is +m (with a periodic channel
hint, default 25m); +nologged allows users without an X username too.
!set +voiceme !set +onlyonmode · !set +nologged · !set voiceme-showtime <period> # users then do: /msg BotNick voiceme #channel
VoiceOnMsg
Manager+Auto-voices active chatters (stock default: after 3 lines) and devoices them after idling too long (default: 2h). Users with access are ignored.
!set +voiceonmsg !set voiceonmsg-linenum <lines> · !set voiceonmsg-idletime <duration>
Private
Manager+Makes the channel access-only: anyone without bot access (or an exception) is banned on join.
!set +private !private add <nick> <ip|mask> · list · del <nick>
Stock defaults: ban 60m · mask *!*@host
AutoUpdate NEW in 2.5.5
Boss ownerLets the script update itself from GitHub when a new version or bugfix is
released — automatically on a timer, or by command. All BT files and the settings from
BlackTools.tcl are backed up and restored; the bot can auto-restart when an update
requires it. Config: update_on (kill switch), update_type
(0 = timer + command, 1 = command only), update_time_check (stock: 60m).
!update <on|off> # enable/disable autoupdate !update check # check for new versions !update start # run the update now !update time [period] # get/set the check interval (Xm/Xh/Xd)
Alias NEW in 2.5.5
Voice+Lets users create their own personalized commands on top of any BT command, with
%1%, %2%… as argument placeholders. Aliases follow the user (renamed with
chuser, removed when the user is deleted or expires).
!alias add <command> <BT command> [arguments] !alias del <command>
!alias add lamer b %1% 0 You are a lamer !! # then: !lamer BadGuy !alias add beer cycle %1% %2% Gone for a beer, back soon
Vote NEW in 2.5.5
Manager+ to toggleChannel voting system: open a voting with multiple options, an optional expiry
time, and choose whether only users with access or everyone may vote. Users answer with the option
letter. +votegreet tells joiners when votings are open.
!set +vote !vote add <vote_name> -option <opt1> -option <opt2>.. [-time DD/MM/YY HH:MM] [-type 1|0] !vote <ID> <letter> # cast your vote !vote list [ID] · !vote time <ID> <DD/MM/YY HH:MM> · !vote end <ID> · !vote del <ID>
!vote add NewTopic -option Keep it -option Change it -time 31/12/25 20:00 -type 0Optional settings: vote-mask (voter identity mask, stock
*!*@host) · -type default: all users
Next
Manager+Help-queue system (built for support channels like #TCL-HELP): users wait in line, helpers voice
the next one in order. +nextshortcmd enables the short aliases.
!set +next !next # voice the next user in the queue !next list · !helped <nick> · !noidle <nick> · !skip <nick>
Settings: next-reason · next-bantime (noidle ban, default 1m)
TopWords
Manager+Records chat statistics per user (words, lines, letters — daily and total).
+accessonly restricts counting to users with bot access.
!set +topwords !topwords <nick> [total|reset] !set +accessonly
Quote · QuoteOfDay
Manager+Channel quote database with add/search/list/delete — plus an optional "Quote of the Day" that posts
a random stored quote on an interval (stock default: every 3h). Since 2.5.5 the
quote:usage config setting chooses who may add/list/remove quotes: users with access
only (stock) or everyone.
!set +quote !q <text> # add (use ~ for multi-sentence) !q <word> # search !q list · !q del <no.> !set +quoteofday · !set quoteofday-showtime <period>
Note
Manager+ to togglePrivate note system: store personal notes or send them to other handles — delivered when they next
appear. The bot also notes global owners whenever it gets banned or locked out of a channel. Inbox
expires after 365 days (per-user override: !myset noteexpire).
!set +note !note send <handle> <message> !note <read|list|inbox> · !note del <no.|all>
BackChan (ChanReport)
Manager+Gives the channel a private "back-channel" where the bot reports every ban it sets on the main channel — and where you can issue ban commands that apply to the main channel. One backchan per channel.
!set backchan <#backchan>
!set backchan #channel-opsBanStats
Manager+Keeps statistics of every kick and ban on the channel (feeds the !stats command).
Daily counters reset at midnight.
!set +banstats !banstats <total|reset>
Language
Manager+Sets the channel's reply language and the language used in kick/ban reasons. Available:
EN (english) · RO (romanian). Each user can override with
!myset lang.
!set lang <EN|RO>
Misc flags: Forward · Invisible · ExpireBans
Boss owner+forward forwards PMs the bot receives (from strangers) to a channel.
+invisible hides the channel from the bot's channel list. expirebans sets
how long channel bans live before auto-removal (stock default: 120m; 0 = never remove).
!set +forward · !set +invisible · !set expirebans <period>
#Personal settings — !myset
Every user with access carries their own preferences, applied wherever they use the
bot. Append show to view a value or reset to clear it.
!myset
Voice+!myset <option> [value] [show|reset]
| Option | What it does | Example |
|---|---|---|
lang | Your reply language (EN/RO) | !myset lang EN |
output | How the bot answers you: NOTICE or CHAN | !myset output chan |
mychar | Your personal trigger character | !myset mychar . |
colors | 4 personal reply colours (bold, red, grey, green…) | !myset colors bold red grey green |
greet | Your join greet/info line (see !addinfo) | !myset greet Hello there! |
mychan | Base channel for PRIVMSG commands — skip typing #channel | !myset mychan #channel |
auto | Your own automode (+/-o, +/-v; owners may add -global) | !myset auto +v |
autoinvite | Bot invites you automatically if you get banned out | !myset autoinvite #channel ON |
noteexpire | Auto-expiry period for your note inbox | !myset noteexpire 90d |
addhost / delhost | Manage your own hostmasks | !myset addhost *!*@me.users.undernet.org |
handle | Change your own handle | !myset handle NewName |
notes | Accept notes ON/OFF | !myset notes ON |
#Eggdrop.conf via IRC — the egg settings
Boss owner Boss owners can edit the bot's config
files straight from IRC — no shell needed. View current values with !h egg; change them with
!set <option> <value>.
| Option | Controls | Current / default |
|---|---|---|
nick | Bot nickname (permanent) | — |
realname | IRC real-name field (needs restart) | — |
away | Away message on connect (empty = none) | "" |
homechan | Home channel — joined first, receives abuse/ban reports, never purged | #no_home_chan (unset) |
chanserv / hostchanserv | Service nick & host | X / x@channels.undernet.org |
userlogin / userpass | X username & password (password displays masked) | — |
cmdchar | Trigger characters (several allowed) | ! . ` ^ |
defaultlang | Script default language | EN |
defaultoutput | Reply method: 0 NOTICE · 1 CHAN · 2 PRIVMSG | 0 (NOTICE) |
add-mask | Hostmask style for !add (1–5, see masks) | 1 |
add-defaultmask | Mask used when the added user is offline | *!*@%user%.users.undernet.org |
floodmenuprot | Command flood limit (cmds:sec) | 3:5 |
floodmsgprot | PRIVMSG flood limit | 10:10 |
floodnotcprot | NOTICE flood limit | 2:2 |
massfloodmsgprot / massfloodsilencetime | Botnet mass-flood shield (since 2.5.5 the PM antiflood action uses IGNORE) | 0:0 / 60s |
chanremove-setting | Wipe all channel data on channel removal (1/0) | 0 |
user-expire | Remove inactive users after N days | 1500 |
banmethod-expire | How long warn/kick escalation counters live | 60m |
broadcast-showtime | AutoBroadcast interval | 55m |
pagelimit | Entries per page in list outputs | 7 |
antibotidle | Keep the eggdrop itself from idling (1 = no idle, 0 = idle) — new in 2.5.5 | 0 |
BlackTools.tcl
directly): dns_onjoin (DNS lookups on join, off by stock — faster on busy channels),
the AutoUpdate block (update_on, update_type,
update_time_check), and the ChanServ mass-ban detector
(chanserv:percent_ban 50%, chanserv:suspend_level 400,
chanserv:suspend_time 1d) which suspends anyone who mass-bans through X.!set cmdchar ! . !set homechan #channel !set defaultoutput 0
#Native eggdrop settings
These are standard eggdrop channel flags — not BlackTools features — but
!set manages them too, so they're documented here. View them with
!h chaninfo.
| Setting | What it does |
|---|---|
+enforcebans | Kick users matching a freshly-set ban |
+dynamicbans | Only place bans on the channel when someone matching joins (keeps +b list short) |
+userbans / +userexempts / +userinvites | Allow bans/exempts/invites to be set directly on IRC |
+dynamicexempts / +dynamicinvites | Only activate +e/+I entries when needed |
+autoop / +autovoice / +autohalfop | Auto-op/voice/halfop users carrying the +o/+v/+l flag on join |
+bitch | Only +o-flagged users may hold @ (insecure, not recommended) |
+greet | Say users' greet lines on join (enables the Greet/Count module output) |
+protectops / +protectfriends / +protecthalfops | Re-op/halfop protected users if they lose status |
+dontkickops | Never kick users with +o flag |
+revenge / +revengebot | Punish whoever deops/kicks/bans the bot (or valid ops) |
+inactive | Leave the channel without losing its settings |
+secret | Hide the channel from the botnet |
+shared | Share channel user records across the botnet |
+cycle | Cycle the channel when it has no ops |
+nodesynch | Tolerate mode changes from non-ops (plays nice with services) |
+statuslog | Log the channel status line every 5 minutes |
+static | Only permanent owners may remove the channel |
chanmode | Enforced channel modes, e.g. !set chanmode +ntk key |
ban-time | Eggdrop-internal temp-ban lifetime (BlackTools uses its own expirebans instead) |
flood-chan / -join / -kick / -ctcp / -nick / -deop | Native flood limits as events:seconds; 0:0 disables |
!set flood-chan 15:60 # 15 lines in 60s from one host = flood
#Ban methods, masks & durations
The 7 ban methods
Every protection has a -banmethod setting choosing how offenders are
escalated. Counters expire after banmethod-expire (60m here). Set with
!set <protection>-banmethod <n>.
| # | Escalation | |
|---|---|---|
1 | warn | just a warning kick/notice |
2 | kick | |
3 | ban | straight to ban |
4 | warn → kick | second offence gets the kick |
5 | warn → kick → ban | the full ladder |
6 | kick → ban | |
7 | warn → ban |
The 5 banmask styles
Every ban command has a -banmask setting choosing the mask shape, built
from nick!user@host:
| # | Mask | Bans on… |
|---|---|---|
1 | *!*@host | host only (the usual default) |
2 | *!user@host | ident + host |
3 | nick!user@host | the exact triple |
4 | nick!*@* | nickname only |
5 | *!user@* | ident only |
Durations
Good to know
!b *!*@192.0.2.1/24 bans the whole range.-c <comment> —
other ops see it when they inspect the ban with !sb.+m for 10 seconds while it cleans.~ —
text1~text2 is delivered as two lines.