.\" nirc-rs — Sovereign Data Terminal
.\" Copyright (C) 2025 Jeremy Anderson
.\" SPDX-License-Identifier: GPL-3.0-or-later
.TH NIRC 1 "2025-07-19" "nirc-rs 0.5.0" "User Commands"
.SH NAME
nirc \- multi-protocol terminal chat client (IRC, Matrix, ADC/DC++, Revolt, BitChat P2P)
.SH SYNOPSIS
.B nirc
[\fIOPTIONS\fR]
.SH DESCRIPTION
.B nirc
is a terminal-based chat client built on the ratatui TUI framework.  It
connects simultaneously to multiple chat protocols through a unified
interface.  All configuration is stored in
.IR ~/.nirc/config.toml .
.PP
Supported protocols:
.TP
IRC
Full command set, TLS, SASL, IRCv3 capabilities (server-time, batch,
account-notify, extended-join), ISUPPORT parsing, auto-reconnect.
.TP
Matrix (0.2.0+)
E2EE via megolm, SSO/OIDC login, SAS emoji verification, message
reactions, device management, token persistence for session resume.
.TP
ADC/DC++ (0.4.0+)
Hub chat, file search, user listing, BINF self-announcement, HPAS
password authentication, keepalive, broadcast messages, C-C file
transfer.
.TP
Revolt/Stoat (0.5.0+)
REST + JSON WebSocket client with email/password or bot-token auth,
server join/leave, member listing, session token persistence.
.TP
BitChat P2P (0.5.0+)
libp2p Gossipsub chat, mDNS local discovery, Identify remote discovery,
direct messages, P2P file transfer via request-response.
.SH OPTIONS
.TP
.B \-h, \-\-help
Print usage information.
.TP
.B \-V, \-\-version
Print version.
.TP
.B \-c, \-\-config <path>
Use an alternate configuration file.
.SH KEY BINDINGS
.TP
.B Tab
Next tab (with unread).
.TP
.B Shift+Tab
Previous tab.
.TP
.B Alt+1 \- Alt+9
Jump to tab 1\(en9.
.TP
.B Alt+N
New tab.
.TP
.B Alt+W
Close current tab.
.TP
.B Alt+L
Toggle winlist visibility.
.TP
.B F1
Debug console.
.TP
.B Ctrl+L
Clear current tab.
.TP
.B PageUp / PageDown
Scroll chat backlog.
.SH COMMANDS
Commands are entered in the input bar prefixed with a slash (\fB/\fR).
Messages without a leading slash are sent to the current tab's channel
or peer.
.SS Connection
.TP
.B /connect <protocol> <server>
Connect to a server.
.I Protocol
is one of
.BR irc ,
.BR matrix ,
.BR adc ,
.BR dc ,
.BR bitchat ,
.BR revolt .
.TP
.B /disconnect [protocol]
Disconnect from a specific protocol, or all.
.TP
.B /newconn [label] [protocol]
Open a new connection dialog.
.TP
.B /server [server] [port]
Switch servers on the current connection.
.TP
.B /quit [reason]
Disconnect from all protocols and exit.
.SS Messaging
.TP
.B /msg <target> <text>
Send a private message.
.TP
.B /me <action>
Send an action (/me) to the current channel.
.TP
.B /say <text>
Send text to the current window.
.TP
.B /notice <target> <text>
Send a notice.
.TP
.B /ctcp <target> [request] [message]
Send a CTCP query.
.TP
.B /raw <line>
.B /quote <line>
Send a raw IRC protocol line.
.SS Channels
.TP
.B /join <channel>
Join a channel or room.
.TP
.B /part [channel]
Leave the current (or specified) channel.
.TP
.B /names [channel]
List users in the current (or specified) channel.
.TP
.B /topic [channel] [topic]
View or set the channel topic.
.TP
.B /invite <nick> [channel]
Invite a user to a channel.
.TP
.B /list [channel]
List available channels.
.TP
.B /who [target]
List users matching a target.
.TP
.B /whois <target>
Get information about a user.
.SS Channel Operations (IRC)
.TP
.B /op <nick>
Give channel operator status.
.TP
.B /deop <nick>
Remove channel operator status.
.TP
.B /kick <nick> [reason]
Kick a user from the channel.
.TP
.B /mode <target> <mode> [params]
Set channel or user mode.
.SS Operator Commands (IRC)
.TP
.B /oper <name> <password>
Become an IRC operator.
.TP
.B /kill <nick> [reason]
Force-disconnect a user from the server.
.TP
.B /kline <mask> [duration] [reason]
Set a K-line ban.
.TP
.B /unkline <mask>
Remove a K-line ban.
.TP
.B /wallops <message>
Send a message to all operators.
.SS User Settings
.TP
.B /nick <newnick>
Change your nickname.
.TP
.B /away [message]
Set or clear away status.
.TP
.B /ignore [target]
Toggle ignore on a user (no argument lists ignored users).
.TP
.B /unblock <target>
Remove a user from the ignore list.
.SS File Transfers
.TP
.B /sendfile <target> <path>
Send a file to a user.
.TP
.B /acceptfile <transfer_id> <save_path>
Accept an incoming file transfer.
.TP
.B /listtransfers
Toggle the file transfer panel.
.SS Matrix Protocol
.TP
.B /matrix login [user_id] <password>
Password login to the current homeserver.
.TP
.B /matrix logout
Log out and clear local crypto state.
.TP
.B /matrix create <name> [alias]
Create a new room.
.TP
.B /matrix invite <user_id>
Invite a user to the current room.
.TP
.B /matrix members [room]
List room members.
.TP
.B /matrix whoami
Show current user ID and device ID.
.TP
.B /matrix devices
List our own devices.
.TP
.B /matrix verify <user_id> [device_id]
Start SAS emoji verification.
.TP
.B /matrix verify-confirm
Confirm a pending SAS verification.
.TP
.B /matrix verify-cancel
Cancel a pending SAS verification.
.TP
.B /matrix react <event_id> <emoji>
React to a message.
.TP
.B /matrix reply <event_id> <text>
Reply to a specific event.
.TP
.B /matrix backfill [count]
Backfill messages (default: 50).
.SS ADC/DC++ Protocol
.TP
.B /adc search <query>
Search the hub for files.
.TP
.B /adc users
List users on the hub.
.TP
.B /adc broadcast <message>
.B /dc bcast <message>
Send a broadcast message to the hub.
.TP
.B /adc get <sid> <path>
.B /adc dl <sid> <path>
Download a file from a user.
.SS Revolt Protocol
.TP
.B /revolt join <invite>
Join a server by invite code.
.TP
.B /revolt leave <server_id>
Leave a server.
.TP
.B /revolt members <server_id>
List server members.
.SS BitChat P2P
.TP
.B /bitchat peers
.B /p2p peers
List discovered P2P peers.
.TP
.B /bitchat dm <peer_id> <message>
.B /p2p msg <peer_id> <message>
Send a direct message.
.TP
.B /bitchat send <peer_id> <path>
.B /p2p send <peer_id> <path>
Send a file via P2P.
.SS Window Management
.TP
.B /win [N]
Switch to window N, or list all windows.
.TP
.B /win list
List all windows.
.TP
.B /win new
Create a new empty window.
.TP
.B /win close [name]
Close a window.
.TP
.B /win name <newname>
Rename the current window.
.TP
.B /jump [target]
Jump to a named window or next unread.
.TP
.B /jumpback
Return to the previous window.
.TP
.B /close [target]
Close a window or part a channel.
.TP
.B /open <name>
Open a query window.
.TP
.B /winlist [HIDDEN|VISIBLE|AUTO]
Toggle winlist visibility.
.SS Utilities
.TP
.B /set <var> [value]
Set a user variable (empty value clears it).
.TP
.B /get <var>
Print a user variable's value.
.TP
.B /alias <name> <command...>
Define an alias.  Supports $1, $2, $* expansion.
.TP
.B /unalias <name>
Remove an alias.
.TP
.B /bind <key> <command...>
Bind a key to a command (e.g. ^R, M-Tab, F5).
.TP
.B /unbind <key>
Remove a key binding.
.TP
.B /eval <text...>
Expand $vars and re-evaluate as a command.
.TP
.B /source <file>
Load and execute a file of commands.
.TP
.B /echo <text>
Display text without sending it.
.TP
.B /clear
Clear the current tab.
.TP
.B /clearall
Clear all tabs.
.TP
.B /save
Save the current configuration.
.TP
.B /help
Show command reference.
.SH CONFIGURATION
The configuration file is read from
.IR ~/.nirc/config.toml .
If absent, sensible defaults are used.  Example:
.PP
.nf
[global]
nickname = "myname"
realname = "My Real Name"
.fi
.PP
.nf
[[servers]]
name = "libera"
protocol = "irc"
address = "irc.libera.chat"
port = 6697
tls = true
sasl = true
password = "hunter2"
.fi
.PP
.nf
[[servers]]
name = "matrix"
protocol = "matrix"
address = "https://matrix.org"
auto_join = ["#nirc:matrix.org"]
[servers.extra]
user_id = "@alice:matrix.org"
password = "hunter2"
.fi
.PP
.nf
[[servers]]
name = "bitchat"
protocol = "bitchat"
address = "/ip4/0.0.0.0/tcp/9394"
[servers.extra]
bootstrap = "/ip4/1.2.3.4/tcp/9394/p2p/QmPeerId"
.fi
.SH FILES
.TP
.I ~/.nirc/config.toml
User configuration.
.TP
.I ~/.nirc/matrix_tokens.json
Persisted Matrix access tokens.
.TP
.I ~/.nirc/revolt_tokens.json
Persisted Revolt session tokens.
.TP
.I ~/.nirc/vault.json
Encrypted identity vault.
.TP
.I ~/.nirc/plugins/
Dynamic plugin directory (libnirc_*.so / *.dylib).
.SH THEMES
Four built-in themes are available:
.BR default ,
.BR solarized ,
.BR gruvbox ,
.BR dracula .
Set via
.B theme
in the configuration file under
.BR [appearance] .
Custom color overrides are also supported.
.SH ENVIRONMENT
.TP
.B NIRC_CONFIG
Override the default configuration path.
.SH SEE ALSO
.BR irssi (1),
.BR weechat (1),
.BR matrix-org/matrix-nio (7)
.SH AUTHOR
Jeremy Anderson <noreply@dcos.net>
.SH BUGS
Report bugs at
.IR https://git.dcos.net/dcosnet/nirc-rs/issues .