293 lines
6.5 KiB
Markdown
Executable File
293 lines
6.5 KiB
Markdown
Executable File
# nirc-rs Quick Start Guide
|
|
|
|
Get connected in under five minutes.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- **Rust** 1.75 or newer — install via [rustup](https://rustup.rs/):
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
cp target/release/nirc-rs ~/.local/bin/
|
|
```
|
|
|
|
### Install via cargo
|
|
|
|
```sh
|
|
cargo install nirc-rs
|
|
```
|
|
|
|
---
|
|
|
|
## First Run
|
|
|
|
Launch nirc-rs with no arguments. It creates `~/.nirc/config.toml` with sensible defaults and opens the TUI:
|
|
|
|
```sh
|
|
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`:
|
|
|
|
```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
|
|
|
|
```toml
|
|
[[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 |