path: root/sirc.1

.TH SIRC 1 "2026" "sirc" "User Commands"
.SH NAME
sirc \- simple terminal IRC client
.SH SYNOPSIS
.B sirc
[\fIOPTIONS\fR]
.SH DESCRIPTION
.B sirc
is a multi-server terminal IRC client written in C.
It connects to one or more IRC servers simultaneously, each in its own
thread, and presents a three-panel TUI: a channel list on the left grouped
by server, a chat area in the centre, and a user list on the right.
The top bar shows the current channel topic.
.PP
Dependencies are ncurses, OpenSSL, and pthreads only.
.SH OPTIONS
.TP
.BI \-\-host " HOST"
IRC server hostname.
Default:
.IR irc.libera.chat .
.TP
.BI \-\-port " PORT"
Server port number.
Default:
.IR 6697 .
.TP
.BI \-\-nick " NICK"
Nickname to use.
Default:
.IR circ_user .
Applied to all configured servers when no
.B \-\-host
is given.
.TP
.BI \-\-channel " CHAN"
Comma-separated list of channels to join on connect.
Example:
.IR "#python,#linux" .
.TP
.B \-\-tls
Enable TLS (default).
.TP
.B \-\-no\-tls
Disable TLS.
Use with plain-text servers, typically on port 6667.
.TP
.BI \-\-sasl\-user " USER"
SASL PLAIN username.
.TP
.BI \-\-sasl\-pass " PASS"
SASL PLAIN password.
.TP
.BI \-\-config " FILE"
Path to a configuration file.
Overrides the default search paths.
.TP
.B \-\-help
Print a short usage summary and exit.
.SH CONFIGURATION
.B sirc
reads its configuration from
.I ~/.sirc
or
.I ~/.config/sirc/config
(first found wins).
Command-line flags always override config file values.
.PP
The file uses
.B key = value
pairs.
Lines beginning with
.B #
are comments.
.PP
.B Multiple servers
are configured with
.B [server]
section blocks.
Each block defines one independent connection.
All configured servers connect simultaneously on startup.
Global keys placed before any
.B [server]
block apply as defaults to all servers.
.SS Global keys
.TP
.B nick
Default nickname inherited by all servers.
.TP
.B ignore
Comma-separated list of nicks to ignore globally.
.SS Per-server keys
.TP
.B host
Server hostname.
.TP
.B port
Port number.
.TP
.B nick
Nickname for this server (overrides the global default).
.TP
.B channel
Comma-separated channels to auto-join on connect.
.TP
.B tls
.BR true " or " false .
.TP
.B sasl_user
SASL PLAIN username.
.TP
.B sasl_pass
SASL PLAIN password.
.SS Example configuration
.PP
.nf
nick    = kky
ignore  = badbot,spammer

[server]
host      = irc.libera.chat
port      = 6697
tls       = true
channel   = #python,#linux
sasl_user = kky
sasl_pass = hunter2

[server]
host    = irc.oftc.net
port    = 6697
tls     = true
channel = #debian

[server]
host    = irc.rizon.net
port    = 6667
tls     = false
nick    = kky_rizon
channel = #rice
.fi
.SH COMMANDS
All commands are entered in the input bar and begin with
.BR / .
Commands act on the current server (the server of the active channel).
.SS Messaging
.TP
.BI /msg " nick text"
Send a private message.
Opens a dedicated buffer for the conversation.
.TP
.BI /notice " target text"
Send a NOTICE.
.TP
.BI /me " text"
Send a CTCP ACTION message
.RI "( " "* nick text" " )."
.TP
.BI /ctcp " nick command"
Send a raw CTCP request.
.SS Channels
.TP
.BI /join " [#chan]"
Join a channel.
.TP
.BI /part " [#chan]"
Leave a channel.
Defaults to the current channel.
.TP
.BI /cycle " [#chan]"
Part and immediately rejoin a channel.
.TP
.BI /names " [#chan]"
Request the user list for a channel.
.TP
.BI /topic " [text]"
With no argument, display the current topic.
With an argument, set a new topic.
.TP
.BI /invite " nick [#chan]"
Invite a user to a channel.
Defaults to the current channel.
.TP
.BI /kick " nick [reason]"
Kick a user from the current channel.
.TP
.BI /mode " [target] [modes]"
Get or set channel or user modes.
.SS Users
.TP
.B /nick
Display your current nickname.
.TP
.BI /nick " newnick"
Request a nickname change.
.TP
.BI /whois " nick"
Perform a WHOIS lookup.
Results appear in the server status buffer.
.TP
.BI /who " [target]"
Send a WHO query for a channel or nick.
.TP
.BI /away " [message]"
Set an away message.
With no argument, clears away status (same as
.BR /back ).
.TP
.B /back
Clear away status.
.TP
.BI /ignore " [nick]"
Add a nick to the ignore list.
With no argument, lists all ignored nicks.
Ignored nicks' messages are silently dropped.
.TP
.BI /unignore " nick"
Remove a nick from the ignore list.
.SS Server
.TP
.BI /list " [pattern]"
Request a list of channels on the current server.
Results appear in the status buffer.
.TP
.BI /raw " line"
Send a raw IRC line directly to the server.
Alias:
.BR /quote .
.TP
.BI /server " host [port]"
Connect to an additional server at runtime.
Inherits the current nick.
.TP
.B /connect
Reconnect the current server.
.TP
.BI /quit " [message]"
Disconnect all servers and exit.
.SS UI
.TP
.B /clear
Clear the scrollback of the current channel.
.TP
.B /help
Print the command reference to the status buffer.
.SH KEYS
.TP
.B Tab
Nick completion.
Matches the word before the cursor against the current channel's user list.
Repeated Tab cycles through matches.
At the start of a line the completed nick is followed by
.BR ": " .
.TP
.BR Ctrl\-N
Switch to the next channel in visual order.
.TP
.BR Ctrl\-P
Switch to the previous channel in visual order.
.TP
.BR PgUp
Scroll the chat area up.
.TP
.BR PgDn
Scroll the chat area down.
.TP
.BR Ctrl\-W
Delete the word to the left of the cursor.
.TP
.BR Up / Down
Step through the input history.
.TP
.BR Left / Right
Move the cursor within the input line.
.TP
.BR Home / End
Jump to the start or end of the input line.
.TP
.BR Delete
Delete the character under the cursor.
.SH LAYOUT
.nf
+------------------+------------------------------------------+----------------+
| CHANNELS         | topic (or blank)                         | USERS (n)      |
|                  +------------------------------------------+                |
| irc.libera.chat  | 12:34 -> alice joined                    | @alice         |
|   *status*       | 12:34 <kky> hello                        | +bob           |
| > #python        | 12:34 <alice> hey!                       |  charlie       |
| + #linux         |                                          |                |
|                  |                                          |                |
| irc.oftc.net     | > _                                      |                |
|   *status*       |                                          |                |
|   #debian        |                                          |                |
+------------------+------------------------------------------+----------------+
.fi
.PP
.B Header bar
.RS
Displays the topic of the active channel, starting from the left edge of the
chat area.
Truncated on the right if too long.
Blank when no topic is set.
.RE
.PP
.B Channel list (left panel)
.RS
Channels are grouped under their server's full hostname.
A
.B ~
prefix on the server name indicates a disconnected server.
The
.B *status*
buffer under each server receives system messages and server output.
.PP
Channel state indicators:
.RS
.TP
.B >
Active channel.
.TP
.B +
Unread messages.
.TP
.B !
Unread mention of your nick.
.RE
.RE
.PP
.B Chat area (centre panel)
.RS
Messages use the following colour scheme:
.RS
.TP
.B <nick>
Per-nick colour derived from a hash of the nick name (bold).
.TP
message body
Plain white.
.TP
own messages
Yellow bold.
.TP
mentions
Red bold.
.TP
actions (/me)
Magenta italic.
.TP
join/part/quit
Gray (dimmed).
.TP
URLs
Blue underline.
.RE
.PP
IRC formatting codes (bold \fB^B\fR, colour \fB^C\fR, italic, underline, reset)
are stripped from all text before display.
.RE
.PP
.B User list (right panel)
.RS
Users are sorted by privilege level, then alphabetically within each group.
Mode symbols are displayed before the nick:
.RS
.TP
.B ~
Founder / owner (red bold).
.TP
.B &
Protected op (red bold).
.TP
.B @
Channel op (red bold).
.TP
.B %
Halfop (yellow bold).
.TP
.B +
Voice (yellow bold).
.TP
(space)
Regular user (white).
.RE
.RE
.PP
.B Input bar (bottom)
.RS
Displays a
.B ">\ "
prompt followed by the input text and a blinking cursor.
.RE
.SH FEATURES
.TP
Multiple simultaneous servers
Each server runs in its own thread with an independent nick, channel set,
and credentials.
.TP
TLS
Connections are encrypted using OpenSSL with full certificate verification
.RB ( SSL_VERIFY_PEER ).
.TP
SASL PLAIN
Per-server authentication before nick registration.
Negotiated via
.BR "CAP REQ :sasl" .
.TP
Auto-reconnect
On disconnect,
.B sirc
waits five seconds then reconnects and rejoins all open channels.
.TP
Per-nick colours
Each nick is assigned a consistent colour derived from a djb2 hash of the
nick string, used in both the chat area and the user list.
.TP
IRC formatting
All mIRC/IRC formatting codes are stripped from incoming text before it is
stored or displayed.
.TP
Topic display
The current channel topic is shown in the header bar and updated live
whenever a
.B TOPIC
message is received.
.TP
URL highlighting
Strings beginning with
.BR http:// ,
.BR https:// ,
or
.B www.\&
are rendered with a blue underline.
.TP
Nick completion
Tab-completion matches the typed prefix against the current channel's user
list.
Cycling with repeated Tab wraps around.
.TP
Ring-buffer scrollback
Each channel stores the last 500 lines in a fixed-size ring buffer with O(1)
insertion.
.TP
Global ignore list
Ignored nicks are dropped across all servers.
The list persists for the session and can be pre-populated in the config file.
.SH LIMITS
.TS
l l.
Max servers	8
Max channels (total)	128
Max users per channel	512
Scrollback per channel	500 lines
Input line length	480 characters
Input history	256 lines
Ignore list	64 nicks
Auto-join channels per server	16
.TE
.SH FILES
.TP
.I ~/.sirc
Primary configuration file.
.TP
.I ~/.config/sirc/config
Alternative configuration file location.
Consulted if
.I ~/.sirc
does not exist.
.SH EXAMPLES
Connect to Libera.Chat with TLS and SASL:
.PP
.nf
sirc --host irc.libera.chat --nick kky --sasl-user kky --sasl-pass hunter2
.fi
.PP
Connect without TLS on the standard plain-text port:
.PP
.nf
sirc --host irc.libera.chat --port 6667 --no-tls --nick kky
.fi
.PP
Join multiple channels on connect:
.PP
.nf
sirc --host irc.libera.chat --nick kky --channel '#python,#linux'
.fi
.PP
Use a custom configuration file:
.PP
.nf
sirc --config ~/work/irc.conf
.fi
.SH BUILDING
.nf
make
make install          # installs to ~/.local/bin/sirc
PREFIX=/usr/local make install
.fi
.SH SEE ALSO
.BR irssi (1),
.BR weechat (1),
.BR nc (1),
.BR openssl (1)
.SH AUTHOR
Emmett1 <me@emmett1.my>
.SH LICENSE
MIT