dcosnet
/
nirc-rs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nirc-rs/QUICKSTART.md

6.5 KiB
Executable File
Raw Permalink Blame History

nirc-rs Quick Start Guide

Get connected in under five minutes.

Prerequisites

  • Rust 1.75 or newer — install via rustup: 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
  • A C compiler (gcc, clang, or cc) — required by some transitive build dependencies
  • TLS libraries: nirc-rs uses tokio-rustls with the webpki-roots CA bundle. No system OpenSSL is required. Everything is statically linked.

Installation

Build from source

git clone https://git.dcos.net/dcosnet/nirc-rs.git
cd nirc-rs
cargo build --release

The compiled binary is at target/release/nirc-rs. Copy it somewhere on your PATH:

cp target/release/nirc-rs ~/.local/bin/

Install via cargo

cargo install nirc-rs

First Run

Launch nirc-rs with no arguments. It creates ~/.nirc/config.toml with sensible defaults and opens the TUI:

nirc-rs

You'll see a single Status tab. The input bar at the bottom is where you type messages and commands. All commands begin with /.

Connecting to IRC

Quick connect

The fastest way to start chatting — connect to Libera Chat over TLS:

/connect irc irc.libera.chat:6697

Wait a moment for the connection to establish (check the status bar). Then join a channel:

/join #rust

A new tab appears for #rust. Start typing to send messages.

SASL authentication

Many IRC networks (including Libera) require or strongly prefer SASL for registered users. Configure it in ~/.nirc/config.toml:

[global]
nickname = "yournick"
realname = "Your Name"
log_level = "info"
auto_connect = ["libera"]

[[servers]]
name = "libera"
protocol = "irc"
address = "irc.libera.chat:6697"
tls = true
auto_join = ["#rust", "#nirc"]

[servers.extra]
sasl_mechanism = "plain"
sasl_username = "your-registered-nick"
sasl_password = "your-account-password"

With auto_connect set, nirc-rs connects and joins channels automatically on every startup.

Basic IRC commands

Command Description Alias
/join #channel Join a channel /j
/part Leave the current channel /close
/msg nick hello Open a private message /m
/me dances Send an action (* yournick dances) —
/names List users in the current channel —
/topic Show the channel topic —
/topic New topic Set the channel topic (requires ops) —
/whois nick Look up user information /wi
/nick newnick Change your nickname —
/away [msg] Set or clear away status —
/notice nick msg Send a notice —
/ctcp nick VERSION Send a CTCP request —
/raw PING :test Send a raw IRC line /quote

Connecting to ADC/DC++

Quick connect

/connect adc hub.example.com:2780

Configured connection

[[servers]]
name = "adc-hub"
protocol = "adc"
address = "hub.example.com:2780"
tls = false
auto_join = []

Then connect with:

/connect adc adc-hub

ADC hubs use a different addressing scheme than IRC. Once connected, you can search for files and browse user listings.

Basic Usage

Sending messages

Type in the input bar and press Enter. In a channel, the message goes to everyone. In a query (private message) window, it goes to that user.

Changing your nickname

/nick newnick

The tab title and status bar update immediately to reflect your new nick.

Joining and leaving channels

/join #channel    # join
/part             # leave the current channel
/join #chan1,#chan2  # join multiple channels (IRC)

Switching between windows

  • Home / End — cycle through previous / next window
  • Ctrl-N — jump to the next window with unread messages
  • Ctrl-B — jump back to the previously active window
  • Ctrl-P — go to previous buffer
  • Ctrl-A — go to next active buffer
  • Tab — if input is empty, cycles to the next window
  • F4 — toggle the window list sidebar

Scrolling

  • PgUp / PgDn — scroll through chat history
  • PgUp locks the view (new messages won't auto-scroll)
  • Insert — scroll to the bottom and re-enable auto-scroll

Key Bindings Cheat Sheet

Key Action
Enter Send message / command
Backspace Delete char before cursor (UTF-8 safe)
Delete Delete char after cursor
Left / Right Move cursor
Home / End Prev / next window
Insert Scroll to bottom (unlock auto-scroll)
Ctrl-N Jump to next unread
Ctrl-B Jump back to previous window
Ctrl-P Previous buffer
Ctrl-A Next active buffer
Ctrl-Z Cycle highlight words
Ctrl-W Delete word before cursor
Ctrl-K Delete to end of line
Ctrl-U Clear entire input line
Ctrl-L Force redraw
Ctrl-C Quit
Tab Complete nick/command, or next window if empty
F1 Toggle dropdown menu
F4 Toggle window list
PgUp / PgDn Scroll chat
Up / Down Command history

File Transfers

Sending a file

/sendfile nick /path/to/file.pdf

Or with the protocol-specific command:

/xfer irc nick /path/to/file.pdf

Receiving a file

When someone sends you a file, you'll see a notification. Accept it:

/acceptfile <transfer-id> ~/downloads/

Monitoring transfers

/transfers

The footer bar also shows a transfer ticker with real-time speed and ETA for active transfers.

Transfers support:

  • Resume — interrupted downloads resume from the last byte
  • SHA-256 verification — hash verified in-flight during transfer
  • Cancellation — cancel anytime without corruption

Encrypted Identity Vault

Store credentials securely in an AES-256-GCM encrypted vault:

/vault create your-password-here
/vault unlock your-password-here
/vault add libera irc nick=yournick;pass=xxx
/vault list
/vault lock

The vault file is at ~/.nirc/vault.json. Keys are wiped from RAM on lock.

Logging

Per-channel logs are written to ~/.nirc/logs/<server>/<window>.log in naim-compatible format:

[12:34:56] <alice> hello world
[12:34:58] * bob waves
[12:35:00] -services- you are now identified

Files rotate at 10 MiB, keeping 3 rotated copies.

Getting Help

Inside nirc-rs, type:

/help

This lists all available slash-commands. Press F1 to open the dropdown menu for a visual command browser.

For bug reports or contributions: https://git.dcos.net/dcosnet/nirc-rs