.\" nirc-rs 
.\" Copyright (C) 2025 Jeremy Anderson
.\" SPDX-License-Identifier: GPL-3.0-or-later
.TH NIRC 1 "2026-07-29" "nirc-rs 0.10.2" "User Commands"
.SH NAME
nirc \- multi-protocol terminal chat client (IRC, Matrix, ADC/DC++, Discord, Stout, Spacebar, Nerimity)
.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
Discord / Stout / Spacebar / Nerimity (0.6.0+)
REST + WebSocket clients for Discord-API-compatible and custom platforms.
.PP
Note: BitChat P2P support was withdrawn in 0.10.2 pending clarity on
Jack Dorsey's BitChat project and the India courts situation.
See
.I NOTICES.md
for the full rationale.
.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 discord ,
.BR stout ,
.BR spacebar ,
.BR nerimity ,
.BR revolt .
(BitChat was removed in 0.10.2 — see NOTICES.md.)
.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 \(em Removed in 0.10.2
BitChat support was withdrawn pending clarity on Jack Dorsey's BitChat
project and the India courts situation. See
.I NOTICES.md
for the full rationale. Existing config entries with
.B protocol = "bitchat"
are silently ignored at load time.
.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 /load [path]
Reload configuration from disk. With no argument, reloads from the
default config location
.RI ( ~/.nirc/config.toml ).
With a path argument, reloads from that file instead; the path supports
.B ~
expansion. Useful for picking up manual edits to the config file
without restarting the client, or for switching between config
profiles. On success, the theme, palette, nickname, and server
presets are re-applied live; on failure (file missing or malformed)
the current config is left untouched and an error is shown in the
Status tab. Pairs naturally with
.B /save
\(en edit the file in your editor, then
.B /load
to pick up the changes.
.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
# BitChat server entries are no longer accepted (removed in 0.10.2).
# Any [[servers]] block with protocol = "bitchat" is silently ignored.
# See NOTICES.md for the rationale.
.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 .