IRCCD(1) - General Commands Manual


irccdctl - irccd controller agent


irccdctl hook-add id path
irccdctl hook-list
irccdctl hook-remove id
irccdctl plugin-config id [variable] [value]
irccdctl plugin-info id
irccdctl plugin-list
irccdctl plugin-load name
irccdctl plugin-reload plugin plugin-unload plugin
irccdctl rule-add [-c channel] [-e event] [-i index] [-o origin] [-s server] accept|drop
irccdctl rule-edit [-a accept|drop] [-c|C channel] [-e|E event] [-o|O origin] [-s|S server] index
irccdctl rule-info index
irccdctl rule-list
irccdctl rule-move from to
irccdctl rule-remove index
irccdctl server-connect [-46s] [-n nickname] [-r realname] [-u username] [-p port] id hostname
irccdctl server-disconnect [server]
irccdctl server-info server
irccdctl server-invite server target channel
irccdctl server-join server channel [password]
irccdctl server-kick server target channel [reason]
irccdctl server-list
irccdctl server-me server target message
irccdctl server-message server target message
irccdctl server-mode server target mode [limit] [user] [mask]
irccdctl server-nick server nickname
irccdctl server-notice server target message
irccdctl server-part server channel [reason]
irccdctl server-reconnect [server]
irccdctl server-topic server channel topic
irccdctl watch [-f native|json]


The irccdctl is the official utility that let you control a running irccd instance. It uses JSON messages over TCP/IP or UNIX sockets with optional SSL layer to send requests. For more information see irccd-ipc(7).

The general syntax for running an irccdctl command is:

irccdctl global-options command command-options command-arguments

The following global-options are available before the command name:


Try to connect using IPv4. Specifying this option unset -6 option, set it explicitly to enable both families.


Try to connect using IPv6. Specifying this option will unset -4 option, set it explicitly to enable both families.

-h hostname

Connect to the IP address or hostname.

-p port

Use the port number or service name.

-P path

Connect to the UNIX local socket specified by path.

Note: options -h and -P are mutually exclusive.



Add a new hook with id as unique identifier and path as local path (on the machine where irccd is running).


List active hooks.


Remove a hook with identifier id.


Manipulate a configuration variable for the plugin specified by id.

If both variable and value are provided, sets the plugin configuration to the respective variable name and value.

If only variable is specified, shows its current value. Otherwise, list all variables and their values.


Get plugin information specified by id.


Get the list of all loaded plugins.


Load a plugin into the irccd instance.

Note: since irccdctl can be used remotely, the argument name will always be evaluated as plugin name and not as a filesystem path. Therefore, the plugin will be searched through the irccd directories.


Reload a plugin specified by id by calling the appropriate onReload event, the plugin is not unloaded and must be already loaded.


Unload the plugin id from the irccd instance.


Add a new rule to irccd.

If no index is specified, the rule is added to the end.

Available options:

-c channel

Match a channel.

-e event

Match an event.

-i index

Rule position.

-o origin

Match an origin.

-p plugin

Match a plugin.

-s server

Match a server.

Note: all options (except -i) may be specified multiple times.


Edit an existing rule in irccd.

Available options:

-a accept|drop

Set action.

-c|C channel

Match or unmatch a channel respectively.

-e|E event

Match or unmatch an event respectively.

-o|O origin

Match or unmatch an origin respectively.

-p|P plugin

Match or unmatch a plugin respectively.

-s|S server

Match or unmatch a server respectively.

Note: all options (except -a) may be specified multiple times.


Show information about the rule specified by index.


List all rules.


Move a rule from the index from at the index specified by to.

The rule will replace the existing one at the given destination moving down every other rules. If destination is greater or equal the number of rules, the rule is moved to the end.


Remove the existing rule at the given index.


Add and connect to a new IRC server. Server with identifier id must not be already present. The argument hostname can be a hostname or IP address.

Available options:

-c character

Specify the command character prefix.

-n nickname

Specify a nickname.

-r realname

Specify a real name.

-u username

Specify a user name.

-p port

Use the specific port, otherwise 6667 is used.


Disconnect and remove server from the irccd registry. If server is not specified, disconnect and remove all servers


Get information about server.


Invite the specified target on the channel.


Join the specified channel, the password is optional.


Kick the specified target from the channel, the reason is optional.


Get the list of all registered servers.


Send an action emote to the target with the given message.


Send a message to the specified target.


Set target or irccd’s user mode.

When target is the bot’s nickname, the command change its mode. Otherwise it applies to a channel and modes are treated differently.

The arguments limit, user, mask are usually only used with channel modes.


Change irccd’s nickname.


Send a private notice to the specified target.


Leave the specified channel, the reason is optional.

Warning: while rare, not all IRC servers support giving a reason to leave a channel, do not specify it if you require portability.


Force reconnection of all servers unless server is specified.


Set the channel new topic. Start watching irccd events. This command will indefinitely wait for new events to arrive from irccd.

Available options:

-f native|json

use JSON or native (human readable) format.


Some shells may discard arguments if they begins with a hash. For instance, bash will not understand the following command:

irccdctl server-join localhost #staff

Instead, enclose the arguments with quotes

irccdctl server-join localhost "#staff"


irccd(1), irccdctl.conf(5)


irccdctl was written by David Demelier <>

macOS 11.2 - @IRCCD_MAN_DATE@