KIRC(1)

NAME
kirc - a tiny, dependency-light IRC client

SYNOPSIS
kirc [-s server] [-p port] [-c channel(s)] [-r realname] [-u username] [-k password] [-a auth] <nickname>

DESCRIPTION
kirc is an extremely fast and simple Internet Relay Chat (IRC) client designed with portability and minimalism in mind, following the "Keep It Simple, Stupid" (KISS) philosophy. It provides a keyboard-driven interface for real-time IRC communication and is optimized to run on systems with minimal dependencies, making it suitable for embedded systems, lightweight containers, and resource-constrained environments.

The primary design principle of kirc is to maintain a small codebase while providing essential IRC functionality. The client follows the Unix philosophy of doing one thing well: it reads from STDIN and prints to STDOUT, allowing all traffic to be easily multiplexed and processed through external commands and shell pipelines. This design enables powerful text filtering, logging, and integration with other Unix tools.

All highlighted text and color can be controlled with ANSI escape sequences, providing full control over output styling and appearance. The client is compatible with both traditional and modern terminal emulators.

For best results and optimal rendering with full color support, use a terminal emulator with 256 color support, such as xterm-256color, GNOME Terminal, Konsole, or iTerm2. Most modern terminal emulators will provide a pleasant experience with kirc with default settings.

OPTIONS
The following options are available. These can also be set using environment variables (see ENVIRONMENT section), which will be overridden by any command-line arguments. The nickname argument is always required.

-s server
    Specifies the IRC server hostname or IP address to connect to. The server name is passed directly to the network layer without validation, so ensure it is correct before connecting.
    Default: irc.libera.chat

-p port
    Specifies the TCP port number used to connect to the IRC server. Standard IRC ports are 6667 (plaintext) and 6697 (with TLS/SSL). Ensure your firewall permits outbound connections on the specified port.
    Default: 6667

-c channel(s)
    Specifies the channel(s) to JOIN upon successful connection. Multiple channels can be specified as a comma-separated or pipe-separated list without spaces (e.g., "#channel1,#channel2"). The first channel in the list will be set as the default target for messages sent without an explicit destination. Channel names must conform to IRC specifications (typically starting with # or &).

-r realname
    Specifies the user's real name as sent during the IRC connection handshake. This value is visible in WHOIS queries and other user information lookups performed by other users. If not specified, the client defaults to using the nickname. This can be any string up to 63 characters.

-u username
    Specifies the USER connection username, which becomes part of your user's hostmask (e.g., user@host). This is displayed in various IRC commands and messages. If not specified, the client defaults to using the nickname. This should typically be alphanumeric characters without spaces.

-k password
    Specifies the plain text PASS connection value, typically used for authentication with the server or services. This is sent during the initial connection phase. Be cautious with this option as the password is visible in the command history and process list. For sensitive configurations, consider using the KIRC_PASSWORD environment variable instead.

-a auth
    Specifies SASL (Simple Authentication and Security Layer) authentication mechanism and token value to be used for connection authentication. The argument value is comprised of a colon-delimited string, where the first token is the authentication mechanism (e.g., "PLAIN", "EXTERNAL", "SCRAM-SHA-256", etc.) and the second string is the mechanism-specific authentication credential (typically BASE64 encoded). For the PLAIN mechanism, you can provide either a pre-encoded BASE64 token or three colon-separated values (authzid:authcid:passwd) which will be automatically encoded.
    Example: "PLAIN:amlsbGVzAGppbGxlcwBzZXNhbWU=" or "PLAIN:alice:alice:password"

EXIT STATUS

0   Successful program execution and normal client termination.

1   Usage error, syntax error, connection failure, or other operational error. Check the terminal output for specific error messages to diagnose the issue.

ENVIRONMENT
The following environment variables can be used to set defaults for connection parameters. All environment variables will be overridden by any corresponding command-line options. This is useful for creating shell aliases or scripts that establish connections with specific parameters.

KIRC_SERVER
    Default IRC server hostname or IP address. Equivalent to the -s option.

KIRC_PORT
    Default server port number. Equivalent to the -p option.

KIRC_CHANNELS
    Default channels to join upon connection (comma or pipe separated). Equivalent to the -c option.

KIRC_REALNAME
    Default real name to use in WHOIS and other user information. Equivalent to the -r option.

KIRC_USERNAME
    Default username for the connection. Equivalent to the -u option.

KIRC_PASSWORD
    Default password for connection authentication. Equivalent to the -k option. Be cautious storing sensitive information in environment variables.

KIRC_AUTH
    Default SASL authentication token and mechanism. Equivalent to the -a option.

COMMANDS
Once connected to an IRC server, kirc supports the following commands. Commands are entered in the input line and executed by pressing ENTER. Text entered without a command prefix is treated as a message to the current target.

/<command>
    Send a raw IRC command to the server. This allows direct access to all IRC protocol commands. Examples include /JOIN, /PART, /WHOIS, /NICK, /KICK, /BAN, /TOPIC, /MODE, /INVITE, and many others. Refer to IRC protocol documentation (RFC 1459) for a complete list of supported commands. The client does not validate or pre-process raw commands, so ensure correct syntax before sending.

/set <target>
    Set the default message channel or nickname to <target>. All subsequent messages entered without an explicit target will be sent to this channel or user. The current target is typically displayed in the status line or prompt area.

/topic <channel> [<topic>]
    Query or set the topic for the specified <channel>. When invoked with only a channel name, the command requests and displays the current channel topic. When a <topic> string is provided, it sets the channel topic to the specified text (subject to channel mode restrictions and operator privileges).

<message>
    Send a PRIVMSG to the currently set target (channel or nickname) with <message> as the message content. This is the primary way to communicate in IRC. Messages are displayed to all users in the target channel or privately to the target user.

@<target> <message>
    Send a PRIVMSG to a specified <target> (channel or nickname) with <message> as the content, without changing the default target. This allows sending one-off messages to other destinations while maintaining your primary conversation context.

/me <action>
    Send a CTCP ACTION command to the currently set target. This displays your message as an action (e.g., "* alice does something") to all users in the target channel or to the target user. Commonly used for expressing actions or emotions.

/ctcp <target> <command> [<arguments>...]
    Send a raw Client-to-Client Protocol (CTCP) command to the specified <target> nickname or channel. Common CTCP commands include "CLIENTINFO", "TIME", "VERSION", "PING", and "DCC". Arguments are separated by spaces. CTCP commands are typically used for client discovery and file transfers (see DCC FILE TRANSFERS section).

KEY BINDINGS
kirc provides standard readline-style key bindings for line editing and command history navigation. The following key combinations are supported:

CTRL+C
    Force quit kirc immediately, disconnecting from the server without sending a QUIT command. This is useful for emergency termination or when the normal exit mechanism is unresponsive.

CTRL+U
    Delete the entire current input line, clearing all typed text and returning to an empty prompt.

Arrow Left (or CTRL+B)
    Move cursor one character to the left.

Arrow Right (or CTRL+F)
    Move cursor one character to the right.

Arrow Up (or CTRL+P)
    Navigate backwards through command history, displaying the previous command entered. Pressing multiple times cycles through older commands.

Arrow Down (or CTRL+N)
    Navigate forwards through command history, displaying the next (more recent) command entered. Pressing at the end of history returns to the empty prompt.

Home (or CTRL+A)
    Move cursor to the beginning of the current input line.

End (or CTRL+E)
    Move cursor to the end of the current input line.

Delete
    Delete the character at the current cursor position.

Backspace (or CTRL+H)
    Delete the character immediately before the cursor position and move the cursor back one character.

EXAMPLES

  Basic usage

kirc alice
    Connect with nickname 'alice' to the default Libera.Chat server (irc.libera.chat:6667). The client will use 'alice' as the username and real name if not otherwise specified.

  Advanced connection parameters

kirc -s irc.example.org -p 6667 -c #foo,#bar alice
    Connect to a custom IRC server (irc.example.org) on port 6667 and automatically join the channels #foo and #bar upon connection. The #foo channel becomes the default message target.

  Environment variables

KIRC_SERVER=irc.libera.chat KIRC_PORT=6697 kirc alice
    Use environment variables to set the server and port for this session. These values can be permanently set in shell profile files for convenience.

  Logging

kirc alice | tee -a kirc-$(date +%Y%m%d).log
    Connect and simultaneously save all output to a log file named with the current date (e.g., kirc-20251229.log). The tee command duplicates output while the \-a flag appends to the file rather than overwriting it.

  SASL authentication

kirc -a PLAIN:alice:alice:password alice
    Connect using SASL PLAIN authentication with automatic token encoding. The client will automatically encode the authzid:authcid:passwd values into the proper BASE64 format required by the SASL PLAIN mechanism.

kirc -a \[dq]PLAIN:$(printf '%s %s %s' 'alice' 'alice' 'password' | base64)\[dq] alice
    Alternatively, generate a BASE64-encoded SASL PLAIN authentication token manually and connect using SASL authentication. The token format is "username username password" (with NULL bytes represented as \0) encoded in BASE64. This demonstrates manual token generation for the SASL PLAIN mechanism.

  TLS/SSL connections via socat

socat tcp-listen:6667,reuseaddr,fork,bind=127.0.0.1 ssl:irc.example.org:6697 & kirc -s 127.0.0.1 alice
    Establish a TLS/SSL encrypted connection to irc.example.org by proxying through socat. Socat listens on local port 6667 and forwards all traffic through an encrypted channel to the remote server's port 6697. This approach is useful when kirc doesn't have native TLS support or when additional connection filtering is needed.

  Proxy connections via socat

socat tcp-listen:6667,fork,reuseaddr,bind=127.0.0.1 proxy:<proxyurl>:irc.example.org:6667,proxyport=<proxyport> & kirc -s 127.0.0.1 -p 6667 alice
    Connect to irc.example.org through an HTTP/HTTPS proxy server using socat as an intermediary. Replace <proxyurl> and <proxyport> with your actual proxy server details. This technique allows IRC access from networks with strict outbound connection policies.

DCC FILE TRANSFERS

  Overview
kirc supports Direct Client-to-Client (DCC) file transfers, including XDCC file requests commonly used on IRC file servers. DCC transfers occur directly between IRC clients without passing through the IRC server, making them independent of server bandwidth limitations.

  Receiving files
When another IRC user sends you a file via DCC SEND, kirc automatically detects the incoming file transfer request and begins downloading the file to the current working directory. The client will display a status message:

    dcc: receiving <filename> from <sender> (<size> bytes)

Transfer progress and completion messages will appear as the file downloads. The file is saved with its original filename. If a file with the same name exists, the behavior depends on the client configuration. Files are saved relative to the current working directory from which kirc was launched.

  XDCC requests
To request a file from an XDCC bot, use the standard XDCC request format:

    /ctcp <botname> XDCC SEND #<packet_number>

The bot will initiate a DCC SEND transfer. kirc automatically handles the incoming transfer and begins downloading the requested file. Multiple XDCC requests can be queued with a single bot, and the bot will process them sequentially.

  Limitations
kirc supports up to 16 simultaneous DCC transfers. Exceeding this limit will reject additional transfer requests. Files are always saved to the current working directory with their original filenames. Ensure adequate disk space is available before initiating large file transfers.

SEE ALSO
irc(1), socat(1)

STANDARDS
kirc implements the Internet Relay Chat protocol as defined in RFC 1459, RFC 2222 (SASL), and IRCv3.1 specifications. The client supports CTCP (Client-to-Client Protocol) extensions for client-to-client communication and file transfers.

BUGS
https://github.com/mcpcpc/kirc/issues