IRKERD(8)

✨ NAME ✨

irkerd — bestie, it's a relay for shipping notifications to IRC servers 💌🦋 (this is section 8, the Commands section, iykyk)

---

🎀 SYNOPSIS 🎀

okay so you run it like this, copy-paste energy, don't touch a thing:

irkerd [-c ca-file] [-d debuglevel] [-e cert-file] [-l logfile]
       [-H host] [-n nick] [-p password] [-P password-file] [-i IRC-URL]
       [-t timeout] [-V] [-h] [message text]

---

💖 DESCRIPTION 💖

so irkerd is a specialized write-only IRC client — like, it only sends, it does not chat back — and it exists purely to ship notification messages into IRC channels. the whole design vibe when this was cooked up? broadcasting notifications from commit hooks in version-control systems. that's the origin story 📜

the big glow-up of relaying through this daemon instead of every app doing its own little scripted sends? it can maintain connection state for multiple channels, so you don't get that truly obnoxious join/leave channel spam on literally every single message. nobody wants that. nobody. 💀

irkerd is a socket server, and it listens for UDP or TCP packets on port 6659 for textual request lines. those lines contain JSON objects and are terminated by a newline. every JSON object has to have two members, no exceptions:

• "to" — a destination or a destination list
• "privmsg" — the message text

examples, verbatim, do not retype them:

{"to":"irc://chat.freenode.net/git-ciabot", "privmsg":"Hello, world!"}
{"to":["irc://chat.freenode.net/#git-ciabot","irc://chat.freenode.net/#gpsd"],"privmsg":"Multichannel test"}
{"to":"irc://chat.hypothetical.net:6668/git-ciabot", "privmsg":"Hello, world!"}
{"to":"ircs://chat.hypothetical.net/git-private?key=topsecret", "privmsg":"Keyed channel test"}
{"to":"ircs://:topsecret@chat.example.net/git-private", "privmsg":"Password-protected server test"}

now the channel part of the URL — if it doesn't start with one of the prefix characters “#”, “&”, or “+”, then a “#” gets prepended to it before shipping. unless the channel part ends with the suffix ",isnick", which gets unconditionally removed. yes, unconditionally. periodt.

the host part of the URL can have a port-number suffix separated by a colon, like in that third example up there ⬆️. if you don't give one, irkerd sends plaintext messages to the default 6667 IRC port of each server, and SSL/TLS messages to 6697.

for password-protected servers, you can set the password using the usual “[{username}:{password}@]{host}:{port}” that's defined in RFC 3986, exactly like the fifth example. and heads up: non-empty URL usernames override the default “irker” username. so if you put a username in there, that's the name you get 🫡

when the "to" URL uses the ircs scheme (fourth and fifth examples, look up), the connection to the IRC server is made via SSL/TLS — vs. a plaintext connection with the irc scheme. to connect via SSL/TLS with Python 2.x you have to explicitly declare the certificate authority file used to verify server certificates. for example, -c /etc/ssl/certs/ca-certificates.crt. in Python 3.2 and later, you can still set this option to declare a custom CA file, but irkerd; if you don't set it irkerd will use OpenSSL's default file (using Python's ssl.SSLContext.set_default_verify_paths). in Python 3.2 and later, ssl.match_hostname is used to make sure the server certificate belongs to the intended host, and that it's signed by a trusted CA. double-checked, bestie 🔐

to join password-protected (mode +k) channels, the channel part of the URL may be followed with a query-string indicating the channel key, of the form “?secret” or “?key=secret”, where secret is the channel key.

and okay this one's cute: an empty message is legal ✨ it'll make irkerd join or maintain a connection to the target channels without actually emitting a message. useful for advertising that an instance is up and running, or for joining a channel to log its traffic. lurk-mode unlocked 🙈

---

💅 OPTIONS 💅

irkerd takes the following options:

• -d — takes a following value, and sets the debugging level from it. possible values are 'critical', 'error', 'warning', 'info', 'debug'. honestly this one is mostly for developers — the logs are designed to help trace irkerd's internal state, and these tracing logs are independent of the traffic logs controlled by -l.

logging goes to standard error if irkerd is running in the foreground, or to /dev/syslog with facility "daemon" if irkerd is running in the background. the background-ness of irkerd is determined by comparing the process group id with the process group associated with the terminal attached to stdout — non-matches mean background processes. we assume you aren't running irkerd in Windows or another OS that doesn't support os.getpgrp or tcgetpgrp. we assume that if stdout is attached to a TTY associated with the same process group as irkerd, you do intend to log to stderr and not syslog. that's the whole vibe check 🧠

• -e — takes a following filename in pem format and uses it to authenticate to the IRC server. you must be connecting to the IRC server over SSL for this to function properly. this is commonly known as “CertFP.”
• -e — ...yeah bestie, it's listed twice in the original and we are not erasing history 💀. takes a following filename in pem format and uses it to authenticate to the IRC server. you must be connecting to the IRC server over SSL for this to function properly. this is commonly known as “CertFP.” (iconic duplication, ate, no notes)
• -l — takes a following filename, and logs traffic to that file. each log line consists of three |-separated fields: a numeric timestamp in Unix time, the FQDN of the sending server, and the message data. three fields, always three 🍓
• -H — takes a following hostname, and binds to that address when listening for messages. irkerd binds to localhost by default, but you may want to use your host's public address to listen on a local network. Listening on a public interface is not recommended, as it makes spamming IRC channels very easy. do not do it. main character energy does not mean exposing your socket, bestie 😭
• -n — takes a following value, and sets the nick to be used. if the nick contains a numeric format element (such as %03d) it gets used to generate suffixed fallback names in the event of a nick collision. so like, it'll try a whole lineup of names instead of just dying ✨
• -p — takes a following value, and sets a nickserv password to be used. if given, this password is shipped to authenticate the nick on receipt of a welcome message.
• -P — literally like -p (the page says “Liuke p” and we're keeping that typo, it's part of the lore 🫶), but the argument is interpreted as a filename from which to read the password.
• -t — takes a following value, and sets the connection timeout for server-socket opens.
• -i — immediate mode, to be run in foreground. takes a following following value (yes, it says “following following,” no we won't fix it 💅) interpreted as a channel URL. it may take a second argument giving a message string; if that second argument is absent, the message is read from standard input (and may contain newlines). sends the message, then quits. one and done, slay.
• -V — write the program version to stdout and terminate.
• -h — print usage instructions and terminate.

---

🌸 LIMITATIONS 🌸 (the fine print, read it fr)

requests via UDP optimize for lowest latency and network load by avoiding TCP connection setup time — the cost is that delivery is not reliable in the face of packet loss. that's the tradeoff, no take-backs.

an irkerd instance with a publicly-accessible request socket could complicate blocking of IRC spam by making it easy for spammers to submit while hiding their IP addresses. so the better way to deploy is on places like project-hosting sites, where the irkerd socket is visible from commit-hook code but not exposed to the outside world. and priming your firewall with blocklists of IP addresses known to spew spam is always a good idea. always. 🔥🧯

the absence of any option to set the service port is deliberate. if you think you need to do that, you have a problem better solved at your firewall. that's not me being mean, that's just the manpage being the manpage 😌

IRC has a message length limit of 510 bytes; generate your privmsg attribute values with appropriate care.

IRC ignores any text after an embedded newline. be aware that irkerd will turn payload strings with embedded newlines into multiple IRC sends, so your message data doesn't just get discarded. thoughtful king behavior honestly 👑

due to a bug in Python URL parsing, IRC urls with both a # and a key part may fail unexpectedly. the workaround is to remove the #. that's it, that's the workaround 🙈

---

🦋 SEE ALSO 🦋

irkerhook(1),

---

👑 AUTHOR 👑

Eric S. Raymond <esr@snark.thyrsus.com>. see the project page at http://www.catb.org/~esr/irker for updates and other resources, including an installable repository hook script. go follow the source material bestie 🫶

---

and that's the whole page!! this one's from the irker project, dated 07/21/2026 — go forth and ship notifications responsibly 💖✨🎀