# 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