BlackTools Documentation

The Ultimate Channel Control Script — One TCL. One smart Eggdrop.
A complete reference for every command, protection and module.

v2.5.5 Eggdrop ≥ 1.8 Tcl ≥ 8.5 Undernet · X service EN · RO · ES · FR by BLaCkShaDoW · tclscripts.net

#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.

ScriptBlackTools v2.5.5 (GitHub master, 2021)
AuthorDaniel Voipan (BLaCkShaDoW) — www.tclscripts.net
RequirementsEggdrop 1.8.x or newer · Tcl 8.5 or newer
LanguagesEnglish · Romanian · Spanish · French (lang files auto-loaded from lang/)
Home channelSet via black(homechan) in BlackTools.tcl (default: none)
Network servicesUndernet X (x@channels.undernet.org) — auto-login supported
Online help#TCL-HELP on Undernet · GitHub
The two most important commands: !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

FeatureDescription
AutoUpdateThe 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.
AliasUsers can build their own personalized commands on top of BT commands, with %1%/%2% argument placeholders.
VoteFull channel voting system: open votings with multiple options, expiry times, access-only or everyone participation, and result listings.
NoProxyNew protection that bans users joining from IPs identified as proxies. The ban reason supports an %isp% placeholder.
AntiBotIdleNew egg setting that keeps the eggdrop itself from idling on the server.
ChanServ mass-ban detectorThe 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

ChangeDetail
DCC party-line supportAll commands now work through DCC chat: .bt <command> [#channel] [arguments] (with !myset mychan set, the channel can be omitted).
LanguagesSpanish translation added; French language files are also shipped.
GuestNick removedThe GuestNick module was removed in the 2021-03-15 update.
Quote access controlNew quote:usage setting: choose whether only users with access, or everyone, may add/list/remove quotes.
AntiColor tuningNew option to punish only specific colour codes (anticolor:specific_colors).
DNS on-join toggleblack(dns_onjoin) lets you disable DNS lookups on join (faster on big channels).
Flood action changeThe private-message antiflood action changed from server SILENCE to IGNORE.
FixesGag 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.

shell
# 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
Warning: running BlackTools together with the A&A script "works in theory" only — the author explicitly does not support that combination.

The directory layout that must live under scripts/:

BlackTools.tcl — main config BlackTools/BT.Core.tcl BlackTools/BT.Ban.tcl — ban engine BlackTools/BT.Loader.tcl BlackTools/BT.Binds.tcl BlackTools/BT.Timers.tcl BlackTools/Addons/ — http, json, github BlackTools/Commands/ — 10 files BlackTools/Modules/ — 26 files BlackTools/Protections/ — 19 files BlackTools/lang/ — EN · RO · ES · FR

#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.

syntax
!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)
Convention used below: <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 access

The most important command. Shows all commands available at your access level, plus category submenus. Disabled commands are hidden or greyed out.

syntax
!h [category]       # categories: cmds · ban · add · manager · master · owner
                      #             btinfo · chaninfo · module · egg
examples
!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 access

The built-in user manual. Displays usage information for every command, protection and module — the same content as this page, live on IRC.

syntax
!man <command>
examples
!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.

LevelScopeEggdrop flagTypical powers
Voicechannel|Vvoice self, seen, invite, kick/warn, myset, h/man
Opchannel|O+ op/deop, modes, topic, cycle, most ban commands
Adminchannel|A+ say/act, add users, suspend, black/stick bans, stats
Managerchannel|M+ set/unset channel settings, enable/disable commands, exempt, purge, del/chuser
Masterglobalomanager powers on every channel + addchan/delchan, suspend chans, status
Ownerglobalm+ global bans, broadcast, die/restart/jump, cp, TCL loading
Boss ownerglobalneverything, incl. editing eggdrop.conf settings from IRC (egg)
Two auxiliary levels exist for the userlist: PROTECT (never punished by protections) and BAN (auto-banned on sight). Ops and voices can additionally be shielded per-channel with !set +oprotect / +vprotect / +hoprotect.

#General commands

Everyday commands available from the lowest access level upward.

!version

Any access

Displays the BlackTools version the eggdrop is running.

example
!version

!i  /  !invite

Voice+

Invites a user to the channel. The bot must be opped (@) for the invite to work.

syntax
!i <nick>          # in channel
/msg BotNick i #channel <nick>
example
!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).

syntax
!seen <nick|ip|host>
!seen global <nick|ip|host>       # owners+ — all channels
examples
!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.

syntax
!activ <nick>

!for

Voice+

Makes multiple eggdrops (all running BlackTools) execute the same command simultaneously — handy when several bots guard the channel.

syntax
for <botnick1>,<botnick2>.. <command> [option]
example
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.

syntax
!info <handle|#chan>
examples
!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.

syntax
!addinfo <text|reset>
example
!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).

syntax
!v [nick1] [nick2]..
!v +        # mass voice everyone
!v -        # mass devoice
example
!v JohnDoe JaneDoe

!o

Op+

Gives or removes op (@) for one or more users. With no nick, ops you.

syntax
!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.

syntax
!ho [nick1] [nick2]..

!mode

Op+

Applies or removes channel modes.

syntax
!mode <+/-modes>
examples
!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.

syntax
!t <text>
example
!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).

syntax
!r [#chan]

!cycle

Op+

Makes the bot cycle (part and re-join) the channel, optionally waiting a given duration.

syntax
!cycle [duration|reason]

!omsg

Op+

Sends a message to all users with op (@) on the channel — or on every channel with all.

syntax
!omsg <#chan|all> <text>
example
!omsg #channel Watch for the spambot wave, set +m if it gets bad

!say

Admin+

Makes the bot say a message to the channel.

syntax
!say [#chan] <message>
example
!say Quiz night starts in 10 minutes!

!act

Admin+

Makes the bot send an action (/me) to the channel.

syntax
!act [#chan] <message>
example
!act waves at everyone

!msg

Owner+

Sends a message to any target — a channel, a nick (query) or a chat window.

syntax
!msg [target] <message>

!broadcast

Owner+

Sends a message to all channels the bot is in.

syntax
!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.

syntax
!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.

syntax
!k <nick|mask> [reason]
examples
!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.

syntax
!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).

syntax
!b [-regex] <nick|mask|regex> [-level] [duration] [reason] [-c comment]
!b [-regex] <nick|mask|regex> [-level] [duration] [global|link] [reason]   # owner+
examples
!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.

syntax
!ub [-regex] <nick|mask|id|regex> [global|link]
examples
!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).

syntax
!sb [-regex] <nick|mask|id|regex> [global]
example
!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.

syntax
!banlist <all|handle|regex|gag|other>
!banlist global                    # owner+

!black

Admin+

Bans a user permanently (blacklist). Equivalent to !b ... 0.

syntax
!black <nick|mask> [reason] [-c comment]
example
!black KnownTroll repeat offender -c do not remove

Optional 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.

syntax
!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.

syntax
!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.

syntax
!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.

syntax
!mb <nick> [reason]

Optional settings: mb-reason · mb-bantime

!dr

Op+

Bans with a default DRONE reason — for compromised clients/drones. Default: 15d.

syntax
!dr <nick|mask>

Optional settings: dr-reason · dr-bantime · dr-banmask

!vr

Op+

Bans with a default VIRUS/TROJAN reason. Default: 3d.

syntax
!vr <nick|mask>

Optional settings: vr-reason · vr-bantime · vr-banmask

!bot

Op+

Bans with a default BOT reason — for unauthorised bots. Default: 7d.

syntax
!bot <nick|mask>

Optional settings: bot-reason · bot-bantime · bot-banmask

!spam

Op+

Bans with a default SPAM reason. Default: 7d.

syntax
!spam <nick|mask>

Optional settings: spam-reason · spam-bantime · spam-banmask

!bw

Op+

Bans with a default bad word reason. Default: 1d.

syntax
!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).

syntax
!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.

syntax
!gag <nick> [duration] [reason]
!ungag <nick|mask>
example
!gag LoudGuy 30m take a breather

Optional 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.

syntax
!exempt add <ip|host> [period] [global] [reason]
!exempt list [global]
!exempt del <ip|host> [global]
example
!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).

syntax
!stats <handle> [total|reset]

!report

Everyone

Lets 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).

syntax
!report <nick> <comment>
example
!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.

syntax
!add <level> <nick|Xusername>
examples
!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.

syntax
!userlist <level|all>       # levels: voice · op · admin · manager · owner · master
example
!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.

syntax
!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.

syntax
!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.

syntax
!auto <+/-o> <nick|handle> [-global]       # auto-op
!auto <+/-v> <nick|handle> [-global]       # auto-voice
example
!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.

syntax
!s <handle> [duration] [reason]
!us <handle>
example
!s RogueOp 3d abusing kick command

!addhost  /  !delhost

Admin+

Adds or removes a hostmask on a user's record.

syntax
!addhost <handle> <mask>
!delhost <handle> <mask>
example
!addhost JohnDoe *!*@JohnDoe.users.undernet.org

!chuser

Manager+

Renames a user's handle in the bot's database.

syntax
!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.

syntax
!set <+/-flag>                     # toggle
!set <option> <value>              # assign
!set global <option> <value>       # owner+ — all channels
examples
!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.

syntax
!unset <flag|option>
!unset global <flag|option>

!show

Manager+

Shows the current value of any setting.

syntax
!show <setting>
example
!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.

syntax
!disable <command|all> [user] [global]
!enable <command|all> [user] [global]
examples
!disable k TriggerHappyOp     # take !k away from one user
!enable all

!ignore

Manager+

Adds, lists or removes bot-level ignores (default duration: 6h).

syntax
!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).

syntax
!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.

syntax
!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.

syntax
!suspend <#chan> <reason>
!unsuspend <#chan>

!channels

Master+

Lists all channels the bot is joined to (channels flagged +invisible are hidden from non-boss users).

syntax
!channels

!cp

Owner+

Copies configuration from one channel to another.

syntax
!cp <userlist|banlist|settings|badchans> <#chan1> <#chan2>
example
!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).

syntax
!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.

syntax
!uptime
!status

!die · !restart · !rehash · !save

Boss owner

die 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.

syntax
!die [reason]   ·   !restart   ·   !rehash   ·   !save

!jump

Boss owner

Makes the bot connect to a different IRC server.

syntax
!jump [irc server]
example
!jump Ashburn.Va.Us.UnderNet.org

!nick

Boss owner

Changes the bot's nickname. !set nick <newnick> makes it permanent (written to the config).

syntax
!nick <newnick>

!login

Boss owner

Manually logs the bot in to ChanServ (X on Undernet) using the configured username/password. Auto-login is controlled by black(autologin) in BlackTools.tcl.

syntax
!login

!chat

Boss owner

Connects you to the bot's botnet/partyline — same as /CTCP BotNick CHAT.

syntax
!chat

!tcl

Boss owner

Manages Tcl scripts live: list, download from a URL (restricted to *.tcl), load, unload, or inspect.

syntax
!tcl list
!tcl wget <link/name.tcl>
!tcl load <name.tcl>
!tcl unload <name.tcl>
!tcl info <name.tcl>

!timer

Boss owner

PRO module — start/stop internal process timers or list active ones. Do not touch unless you know exactly what you're doing.

syntax
!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 configure

Bans users advertising channels/links (*#*, *www.*, *http://*…). Wildcard word list with exceptions — YouTube links are excepted by default.

syntax
!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 configure

Punishes users who send NOTICEs to the channel.

syntax
!set +antinotice

Stock defaults: ban 2d · method 3 (ban) · mask *!*@host · sets channel mode +mr for 45s during an attack

AntiCTCP

Manager+ to configure

Punishes users who send CTCPs to the channel.

syntax
!set +antictcp

Stock defaults: ban 3d · method 3 (ban) · mask *!*@host · mode +mC for 45s

AntiBadWord

Manager+ to configure

Punishes use of forbidden words/phrases (wildcards). Words can carry their own punishment method: word:6.

syntax
!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 configure

Punishes messages that are too long (stock limit: 215 characters).

syntax
!set +antilongtext

Stock defaults: ban 30m · method 6 · mask *!*@host · setting antilongtextmax

AntiBadQuitPart

Manager+ to configure

Punishes forbidden words in part/quit messages. Extras: +quitpartcolor (colours in quit/part) and +quitpartmsgflood (overlong quit/part messages, default 120 chars).

syntax
!set +badquitpart
!badquitpart add <word> · add +word · list · del <no.>

Stock defaults: ban 1h · mask *!user@host

AntiSpam

Manager+ to configure

Bans 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.

syntax
!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 configure

Punishes repeating the same text (stock default: 3 repeats within 5s).

syntax
!set +antirepeat

Stock defaults: ban 10m · method 7 (warn→ban) · mask *!*@host · setting antirepeat-setting (repeats:seconds)

AntiColor · AntiBold · AntiUnderline · AntiCaps

Manager+ to configure

The 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.

syntax
!set +anticolor · !set +antibold · !set +antiunderline · !set +anticaps

Stock defaults: ban 10m · method 7 (warn→ban) · mask *!*@host each

RepetitiveChars

Manager+ to configure

Punishes consecutive repeated characters (stock default: 10 in a line — "aaaaaaaaaa").

syntax
!set +repetitivechars

Stock defaults: ban 10m · method 7 · mask *!user@host · setting repetitivechars-char

BadNick

Manager+ to configure

Bans nicknames containing forbidden words (checked on join and nick change). Method 1 warns first and gives 30s to change nick before banning.

syntax
!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 configure

Bans idents containing forbidden words (checked on join).

syntax
!set +badident
!badident add <word> · add +word · list · del <no.>

Stock defaults: ban 1h · mask *!user@*

BadRealname

Manager+ to configure

Bans realnames containing forbidden words/links (checked on join).

syntax
!set +badrealname
!badrealname add <word> · add +word · list · del <no.>

Stock defaults: ban 2h · mask *!*@host · default patterns include *www.*, *#*, *http://*

BadHost

Manager+ to configure

Bans users whose IP/vhost contains forbidden words.

syntax
!set +badhost
!badhost add <ip|mask> · add +word · list · del <no.>

Stock defaults: ban 3h · mask *!*@host

AntiJoinFlood

Manager+ to configure

Counters 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.

syntax
!set +antijoinflood
!set joinflood <joins:seconds>

Stock defaults: ban 1h · mask *!*@host · see also +antijoinpart

AntiChanFlood

Manager+ to configure

Punishes text flooding (stock default: 4 lines / 5s). Locks the channel +mr for 45s while it cleans up.

syntax
!set +antichanflood
!set chanflood <lines:seconds>

Stock defaults: ban 10m · method 6 (kick→ban) · mask *!*@host

NickFlood

Manager+ to configure

Punishes rapid nick-changing (stock default: 3 changes / 120s).

syntax
!set +nickflood

Stock defaults: ban 10m · method 7 (warn→ban) · mask nick!user@host · setting nickflood-repeat

NoProxy NEW in 2.5.5

Manager+ to configure

Bans 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)).

syntax
!set +noproxy

Stock defaults: ban 1h · settings: noproxy-reason · noproxy-bantime

InviteBan

Manager+ to configure

Bans users who try to invite the bot into unauthorised channels.

syntax
!set +inviteban

Stock defaults: ban 3h · mask *!*@host

AntiTake (dontop / dontdeop)

Manager+ to configure

Anti-takeover. +dontdeop: unauthorised users who deop others get deopped, victims get re-opped. +dontop: unauthorised users who op someone get both parties deopped.

syntax
!set +dontdeop
!set +dontop

SecureMode

Manager+ to configure

Undernet-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.

syntax
!set +securemode
!securemode add <ip|mask> · del <no.> · list
!set +strictsecured

CloneScan

Manager+ to configure

Periodically scans for clones (multiple connections from one host) and bans them. Stock defaults: max 3 clones, scan every 45m, ban 180m.

syntax
!set +clonescan
!clonescan add <ip|mask> # whitelist · del <no.> · list

Settings: clonescan-maxclone · clonescan-bantime · clonescan-reason · clonescan-scantime

BadChan

Manager+ to configure

Bans 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.

syntax
!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.

syntax
!set +xtools

XOnly

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.

syntax
!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.

syntax
!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.

syntax
!greet <ON|OFF> · !greet set <message>
!leave <ON|OFF> · !leave set <message>
!set greet-method <NOTICE|PRIVMSG> · !set leave-method <NOTICE|PRIVMSG>
example
!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 ~.

syntax
!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.

syntax
!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.

syntax
!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.

syntax
!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.

syntax
!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.

syntax
!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.

syntax
!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.

syntax
!set +private
!private add <nick> <ip|mask> · list · del <nick>

Stock defaults: ban 60m · mask *!*@host

AutoUpdate NEW in 2.5.5

Boss owner

Lets 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).

syntax
!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).

syntax
!alias add <command> <BT command> [arguments]
!alias del <command>
examples
!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 toggle

Channel 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.

syntax
!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>
example
!vote add NewTopic -option Keep it -option Change it -time 31/12/25 20:00 -type 0

Optional 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.

syntax
!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.

syntax
!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.

syntax
!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 toggle

Private 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).

syntax
!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.

syntax
!set backchan <#backchan>
example
!set backchan #channel-ops

BanStats

Manager+

Keeps statistics of every kick and ban on the channel (feeds the !stats command). Daily counters reset at midnight.

syntax
!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.

syntax
!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).

syntax
!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+
syntax
!myset <option> [value] [show|reset]
OptionWhat it doesExample
langYour reply language (EN/RO)!myset lang EN
outputHow the bot answers you: NOTICE or CHAN!myset output chan
mycharYour personal trigger character!myset mychar .
colors4 personal reply colours (bold, red, grey, green…)!myset colors bold red grey green
greetYour join greet/info line (see !addinfo)!myset greet Hello there!
mychanBase channel for PRIVMSG commands — skip typing #channel!myset mychan #channel
autoYour own automode (+/-o, +/-v; owners may add -global)!myset auto +v
autoinviteBot invites you automatically if you get banned out!myset autoinvite #channel ON
noteexpireAuto-expiry period for your note inbox!myset noteexpire 90d
addhost / delhostManage your own hostmasks!myset addhost *!*@me.users.undernet.org
handleChange your own handle!myset handle NewName
notesAccept 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>.

OptionControlsCurrent / default
nickBot nickname (permanent)
realnameIRC real-name field (needs restart)
awayAway message on connect (empty = none)""
homechanHome channel — joined first, receives abuse/ban reports, never purged#no_home_chan (unset)
chanserv / hostchanservService nick & hostX / x@channels.undernet.org
userlogin / userpassX username & password (password displays masked)
cmdcharTrigger characters (several allowed)! . ` ^
defaultlangScript default languageEN
defaultoutputReply method: 0 NOTICE · 1 CHAN · 2 PRIVMSG0 (NOTICE)
add-maskHostmask style for !add (1–5, see masks)1
add-defaultmaskMask used when the added user is offline*!*@%user%.users.undernet.org
floodmenuprotCommand flood limit (cmds:sec)3:5
floodmsgprotPRIVMSG flood limit10:10
floodnotcprotNOTICE flood limit2:2
massfloodmsgprot / massfloodsilencetimeBotnet mass-flood shield (since 2.5.5 the PM antiflood action uses IGNORE)0:0 / 60s
chanremove-settingWipe all channel data on channel removal (1/0)0
user-expireRemove inactive users after N days1500
banmethod-expireHow long warn/kick escalation counters live60m
broadcast-showtimeAutoBroadcast interval55m
pagelimitEntries per page in list outputs7
antibotidleKeep the eggdrop itself from idling (1 = no idle, 0 = idle) — new in 2.5.50
Also new in the 2.5.5 config file (edited in 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.
examples
!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.

SettingWhat it does
+enforcebansKick users matching a freshly-set ban
+dynamicbansOnly place bans on the channel when someone matching joins (keeps +b list short)
+userbans / +userexempts / +userinvitesAllow bans/exempts/invites to be set directly on IRC
+dynamicexempts / +dynamicinvitesOnly activate +e/+I entries when needed
+autoop / +autovoice / +autohalfopAuto-op/voice/halfop users carrying the +o/+v/+l flag on join
+bitchOnly +o-flagged users may hold @ (insecure, not recommended)
+greetSay users' greet lines on join (enables the Greet/Count module output)
+protectops / +protectfriends / +protecthalfopsRe-op/halfop protected users if they lose status
+dontkickopsNever kick users with +o flag
+revenge / +revengebotPunish whoever deops/kicks/bans the bot (or valid ops)
+inactiveLeave the channel without losing its settings
+secretHide the channel from the botnet
+sharedShare channel user records across the botnet
+cycleCycle the channel when it has no ops
+nodesynchTolerate mode changes from non-ops (plays nice with services)
+statuslogLog the channel status line every 5 minutes
+staticOnly permanent owners may remove the channel
chanmodeEnforced channel modes, e.g. !set chanmode +ntk key
ban-timeEggdrop-internal temp-ban lifetime (BlackTools uses its own expirebans instead)
flood-chan / -join / -kick / -ctcp / -nick / -deopNative flood limits as events:seconds; 0:0 disables
example
!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
1warnjust a warning kick/notice
2kick
3banstraight to ban
4warn → kicksecond offence gets the kick
5warn → kick → banthe full ladder
6kick → ban
7warn → ban

The 5 banmask styles

Every ban command has a -banmask setting choosing the mask shape, built from nick!user@host:

#MaskBans on…
1*!*@hosthost only (the usual default)
2*!user@hostident + host
3nick!user@hostthe exact triple
4nick!*@*nickname only
5*!user@*ident only
Webchat users (mibbit, kiwiirc, irccloud…) are automatically banned on ident only regardless of the mask setting — their host is shared, their ident carries the user's hex IP.

Durations

10m — ten minutes 3h — three hours 2d — two days 0 — permanent

Good to know

CIDR bans work: !b *!*@192.0.2.1/24 bans the whole range.
Ban comments: nearly every ban command accepts -c <comment> — other ops see it when they inspect the ban with !sb.
Full banlist handling: when the channel +b list fills up (Undernet numeric 478), the bot auto-removes the 10 oldest bans, holding +m for 10 seconds while it cleans.
Multi-sentence texts: greets, quotes, ads and notes split on ~text1~text2 is delivered as two lines.