{{title}} — repartee
Author: outragedevs
Description: repartee — A modern terminal IRC client built with Ratatui, Tokio, and Rust. Scripting, theming, encrypted logging, and more.
Keywords: irc, terminal, tui, client, chat, repartee, ratatui, tokio, rust

# Commands

## Channel

# /clear

## Syntax

    /clear

## Description

Clears all messages from the current buffer's display. This is a visual-only operation — chat logs in the database are not affected. Messages remain searchable via `/log search`.

Works on any buffer type: channels, queries, and server buffers.

## Examples

    /clear

## See Also

/close, /log

# /close

## Syntax

    /close [reason]

## Description

Close the current buffer. For channels, parts the channel with an optional reason. For query windows, closes the window. Server buffers cannot be closed.

## Examples

    /close
    /close Window closed

## See Also

/part, /quit

# /cycle

## Syntax

    /cycle [channel] [message]

## Description

Leave and immediately rejoin a channel. Useful for refreshing your user list, re-triggering auto-op or auto-voice, or clearing stale state. If the channel has a key set, it is preserved for the rejoin.

With no arguments, cycles the current channel. An optional part message can be provided.

## Examples

    /cycle
    /cycle #linux
    /cycle #linux Refreshing...

## See Also

/part, /join

# /except

## Syntax

    /except [mask]

## Description

With no arguments, requests the exception list (+e) from the server. With a mask, sets +e on the current channel. Ban exceptions allow users matching the mask to join even if banned.

## Examples

    /except
    /except *!*@trusted.com

## See Also

/unexcept, /ban, /unban

# /invex

## Syntax

    /invex [mask]

## Description

With no arguments, requests the invite exception list (+I) from the server. With a mask, sets +I on the current channel. Invite exceptions allow users matching the mask to join invite-only channels.

## Examples

    /invex
    /invex *!*@friends.com

## See Also

/uninvex, /invite

# /invite

## Syntax

    /invite <nick> [channel]

## Description

Invite a user to join a channel. Without a channel argument, invites to the current channel. You typically need channel operator status to send invites.

## Examples

    /invite friend              # invite to current channel
    /invite friend #secret      # invite to #secret

## See Also

/kick, /ban

# /join

## Syntax

    /join <channel> [key]

## Description

Join an IRC channel. A `#` prefix is auto-added if missing. Optionally provide a channel key for key-protected channels.

## Examples

    /join #linux
    /join linux
    /join #secret mysecretkey

## See Also

/part, /close

# /names

## Syntax

    /names [channel]

## Description

Display the list of users in a channel. Without arguments, lists users in the current channel. Also sends a NAMES request to the server to refresh the nick list panel.

The output shows each user with their mode prefix (@, +, etc.) and a total user count.

## Examples

    /names              # list users in current channel
    /names #help        # list users in #help

## See Also

/who, /whois

# /part

## Syntax

    /part [channel] [message]

## Description

Leave an IRC channel. With no arguments, leaves the current channel. Optionally specify a channel name and part message.

## Examples

    /part
    /part #linux
    /part #linux See you later

## See Also

/join, /close

# /reop

## Syntax

    /reop [mask]

## Description

With no arguments, requests the reop list (+R) from the server. With a mask, sets +R on the current channel. Reop entries automatically re-op users matching the mask when they rejoin.

## Examples

    /reop
    /reop *!*@ops.net

## See Also

/unreop, /op

# /topic

## Syntax

    /topic
    /topic <text>
    /topic <channel>
    /topic <channel> <text>

## Description

View or set the channel topic.

Without arguments, displays the current topic for the active channel. With only a channel name, requests the topic from the server. With text, sets the topic on the active channel (or on the specified channel).

## Examples

    /topic                          # show current topic
    /topic #help                    # request topic for #help
    /topic Welcome to the channel   # set topic on current channel
    /topic #help Welcome!           # set topic on #help

## See Also

/mode, /names

# /unexcept

## Syntax

    /unexcept <mask>

## Description

Remove an exception (-e) from the current channel by mask.

## Examples

    /unexcept *!*@trusted.com

## See Also

/except

# /uninvex

## Syntax

    /uninvex <mask>

## Description

Remove an invite exception (-I) from the current channel by mask.

## Examples

    /uninvex *!*@friends.com

## See Also

/invex

# /unreop

## Syntax

    /unreop <mask>

## Description

Remove a reop entry (-R) from the current channel by mask.

## Examples

    /unreop *!*@ops.net

## See Also

/reop

## Configuration

# /alias

## Syntax

    /alias                    List all aliases
    /alias <name>             Show a specific alias
    /alias <name> <body>      Define or replace an alias
    /alias -<name>            Remove an alias

## Description

Define custom command aliases. Aliases expand before execution and support template variables, context variables, and command chaining with semicolons.

### Template Variables

- `$0`-`$9` — positional arguments
- `$0-` through `$9-` — all arguments from position N onward
- `$*` — all arguments joined by space

If the alias body contains no `$` references, `$*` is appended automatically. This means `/alias ns /msg NickServ` works the same as `/alias ns /msg NickServ $*`.

### Context Variables

- `$C` or `${C}` — current channel/buffer name
- `$N` or `${N}` — current nick
- `$S` or `${S}` — current server label
- `$T` or `${T}` — current buffer name (same as `$C`)

### Command Chaining

Use `;` to chain multiple commands in one alias:

    /alias j /join $0; /msg $0 hello everyone

### Recursion Guard

Aliases can reference other aliases. Recursion is capped at 10 levels to prevent infinite loops.

Cannot override built-in commands.

## Examples

    /alias
    /alias ns
    /alias ns /msg NickServ $*
    /alias cs /msg ChanServ $*
    /alias j /join $0; /msg $0 hello everyone
    /alias w /who $C
    /alias -ns

## Config

Aliases are stored in the `[aliases]` section of `config.toml`:

    [aliases]
    ns = "/msg NickServ $*"
    cs = "/msg ChanServ $*"
    wc = "/close"
    j = "/join $0; /msg $0 hello everyone"

## See Also

/unalias

# /reload

## Syntax

    /reload

## Description

Reload the configuration file and theme from disk. Useful after manually editing `config/config.toml` or theme files.

## See Also

/set, /items

# /set

## Syntax

    /set [section.field] [value]

## Description

View or change runtime configuration. Settings use dot-notation paths like `general.nick` or `servers.libera.port`. Changes are saved to `config/config.toml` immediately. Credentials (passwords, SASL) are stored in `.env` instead.

With no arguments, lists all settings grouped by section. With just a path, shows the current value. With a path and value, sets the value and saves.

Boolean values accept: `true`/`false`, `on`/`off`, `yes`/`no`. Array values use comma-separated format: `#chan1,#chan2`.

## Examples

    /set
    /set general.nick
    /set general.nick newnick
    /set general.theme tokyo-night
    /set servers.libera.tls true
    /set servers.libera.channels #linux,#irc
    /set display.nick_colors true
    /set display.nick_colors_in_nicklist false
    /set display.nick_color_lightness 0.40

## See Also

/reload, /server, /items

# /spellcheck

Spell checker status and control.

## Description

Two modes: "replace" (default) replaces misspelled words inline — Tab cycles suggestions, Space accepts, Escape reverts. "highlight" marks misspelled words with red underline without changing text. Switch with `/set spellcheck.mode highlight` or `/set spellcheck.mode replace`.

## Usage

    /spellcheck [status|reload|list|get <lang>]

## Subcommands

### status

Show spell checker status: enabled/disabled, active languages, dictionary directory, and number of loaded dictionaries.

### reload

Reload dictionaries from disk. Useful after adding new `.dic`/`.aff` files or changing `spellcheck.languages`.

### list

Fetch the list of available dictionaries from the Repartee dictionary repository. Shows each language with its install status.

### get <lang>

Download a dictionary by language code (e.g. `en_US`, `pl_PL`, `de_DE`). Files are saved to `~/.repartee/dicts/` and the spell checker is automatically reloaded.

## Configuration

    [spellcheck]
    enabled = true
    computing = true           # computing/IT dictionary (7,400+ terms)
    mode = "replace"           # or "highlight"
    languages = ["en_US", "pl_PL", "de_DE"]
    dictionary_dir = ""        # default: ~/.repartee/dicts

Runtime settings:

    /set spellcheck.enabled true
    /set spellcheck.computing true
    /set spellcheck.mode replace
    /set spellcheck.languages en_US,pl_PL,de_DE
    /set spellcheck.dictionary_dir /path/to/dicts

## Computing dictionary

A bundled 7,400-word dictionary of computing/IT terms — programming languages, frameworks, tools, protocols, IRC vocabulary, and more. Prevents false positives on words like `kubectl`, `PRIVMSG`, `IRCnet`, `tokio`, `rustfmt`.

Install from the repartee-dicts repository:

    /spellcheck get computing

Controlled via `spellcheck.computing` (default: `true`). The computing dictionary is checked before language dictionaries — if a word is a known computing term, it's accepted immediately.

## Modes

### replace (default)

Misspelled words are immediately replaced with the first suggestion. Tab cycles through alternatives, Space accepts, Escape reverts.

### highlight

Misspelled words stay as-is but are marked with red underline. A popup shows suggestions for reference. Any keystroke dismisses the popup without changing your text. Non-aggressive — useful if you prefer to fix typos manually.

## Dictionary setup

The easiest way is to use the built-in download command:

    /spellcheck list          # see available dictionaries
    /spellcheck get en_US     # download English (US)
    /spellcheck get pl_PL     # download Polish

Dictionaries are downloaded from the outragedevs/repartee-dicts repository, which provides UTF-8 Hunspell dictionaries sourced from wooorm/dictionaries.

You can also place `.dic`/`.aff` files manually in `~/.repartee/dicts/`:

    ~/.repartee/dicts/en_US.dic
    ~/.repartee/dicts/en_US.aff

For languages not included in our repository, you can find additional UTF-8 Hunspell dictionaries at wooorm/dictionaries (90+ languages).

## Inline correction

When spell checking is active:

1. Type a word and press Space — the word is checked
2. Check order: skip filters (URLs, numbers) → nick list → computing dict → language dicts
3. A word is correct if any source accepts it

### Replace mode (default)

- Misspelled word is replaced with the first suggestion
- Tab cycles through alternatives (replaces inline)
- Space or typing accepts the current correction
- Escape reverts to the original word
- Backspace dismisses and lets you edit manually

### Highlight mode

- Misspelled word stays as-is, marked red + underlined
- Popup shows suggestions for reference only
- Any keystroke dismisses the popup without changing text
- Non-aggressive — fix typos in your own time

## Aliases

`/spell`

## See also

`/set spellcheck.*`

# /unalias

## Syntax

    /unalias <name>

## Description

Remove a user-defined alias. Equivalent to `/alias -name`.

## Examples

    /unalias ns

## See Also

/alias

## Connection

# /autoconnect

## Syntax

    /autoconnect [on|off]

## Description

Toggle the autoconnect flag for the current server's configuration. When autoconnect is on, the client will connect to this server automatically on startup.

Without arguments, shows the current autoconnect status.

## Examples

    /autoconnect
    /autoconnect on
    /autoconnect off

## See Also

/server, /connect

# /connect

## Syntax

    /connect <server-id|label|address>[:<port>] [-tls] [-bind=<ip>]

## Description

Connect to an IRC server. Accepts a configured server ID, label, or a raw address for ad-hoc connections. If the server is already configured, flags override its settings for this connection only.

## Examples

    /connect libera
    /connect irc.libera.chat:6697 -tls
    /connect mynet -bind=192.168.1.100

## See Also

/server, /disconnect, /quit

# /dcc

## Syntax

    /dcc <chat|close|list|reject> [args...]

## Description

Manage DCC (Direct Client-to-Client) CHAT connections. DCC CHAT establishes a direct TCP connection between two IRC users, bypassing the IRC server entirely. Messages are exchanged over a raw TCP socket, not through the IRC network.

DCC CHAT buffers use the `=nick` naming convention (e.g., `=Alice`). Typing in a `=nick` buffer sends text over the DCC connection, not via IRC. The `/msg =nick text` syntax also routes to DCC.

## Subcommands

### chat

Initiate a DCC CHAT or accept a pending request.

    /dcc chat                  Accept the most recent pending request
    /dcc chat <nick>           Initiate DCC CHAT or accept pending from nick
    /dcc chat -passive <nick>  Initiate passive DCC (for NAT/firewall)

When no nick is given, the most recent pending incoming request is accepted. If a pending request from the specified nick exists, it is accepted instead of initiating a new one.

Passive mode (`-passive`) sends a reverse DCC offer — the remote peer opens the listener instead. Use this when your firewall blocks incoming connections.

### close

Close an active DCC CHAT connection.

    /dcc close chat <nick>

The `=nick` buffer remains after closing (with a disconnect message). Use `/close` on the buffer to remove it.

### list

List all DCC connections with their current state.

    /dcc list

Shows: nick, type (CHAT), state (waiting/listening/connecting/connected), duration, and bytes transferred.

### reject

Reject a pending DCC CHAT request and notify the sender.

    /dcc reject chat <nick>

Sends a `DCC REJECT` CTCP notice to the remote client so they know the offer was declined. Requests that time out (5 minutes by default) are silently discarded without sending REJECT.

## Configuration

DCC settings can be changed at runtime with `/set`:

    /set dcc.timeout 300           Seconds before pending requests expire
    /set dcc.own_ip 203.0.113.5    Override IP in DCC offers
    /set dcc.port_range 0          Port range for listeners (0 = OS-assigned)
    /set dcc.max_connections 10    Max simultaneous DCC connections
    /set dcc.autoaccept_lowports false  Allow auto-accept from ports < 1024

## IP Detection

Repartee automatically detects your IP from the IRC socket (like irssi's `getsockname`). If you're behind NAT or connecting through a bouncer, set `dcc.own_ip` to your public/LAN IP.

## Examples

    /dcc chat Alice
    /dcc chat -passive Bob
    /dcc list
    /dcc close chat Alice
    /dcc reject chat Eve
    /msg =Alice hello over DCC!
    /me waves (in a =nick buffer, sent over DCC)

## See Also

/msg, /query, /set

# /detach

## Syntax

    /detach

## Description

Detaches from the current terminal session. The repartee backend continues running in the background — IRC connections stay alive, messages are logged, and scripts keep executing.

After detaching, your terminal is restored and your shell prompt returns.

## Reattaching

Use `repartee a` (or `repartee attach`) from any terminal to reconnect:

    repartee a           # attach to the only running session
    repartee a <pid>     # attach to a specific session by PID

## Keyboard shortcuts

You can also detach with keyboard chords instead of typing the command:

- Ctrl+\ (Ctrl + backslash)
- Ctrl+Z

## Examples

    /detach              # detach from terminal

From your shell after detaching:

    repartee a           # reattach to the session

## Aliases

- `/dt`

## See Also

- Sessions & Detach — full documentation on session management

# /disconnect

## Syntax

    /disconnect [server-id|label] [message]

## Description

Disconnect from an IRC server. With no arguments, disconnects from the server associated with the current buffer. Optionally specify a server by ID or label, and a quit message.

## Examples

    /disconnect
    /disconnect libera
    /disconnect libera Goodbye!

## See Also

/connect, /quit, /server

# /quit

## Syntax

    /quit [message]

## Description

Disconnect from all servers and close the application. An optional quit message is sent to each server. Default message is "kIRC".

## Examples

    /quit
    /quit Goodnight!

## See Also

/disconnect, /close

# /server

## Syntax

    /server [list|add|remove] [args...]

## Description

Manage IRC server configurations. Add, remove, and list servers. Server credentials (passwords, SASL) are stored in `.env`.

## Subcommands

### list

List all configured servers with their connection status.

    /server list

This is the default when no subcommand is given.

### add

Add a new server to the configuration.

    /server add <id> <address>[:<port>] [flags...]

Flags:

- `-tls` — Enable TLS (auto-sets port to 6697)
- `-notlsverify` — Skip TLS certificate verification
- `-noauto` — Don't auto-connect on startup
- `-label=<name>` — Display name
- `-nick=<nick>` — Use a different nick for this server
- `-password=<pass>` — Server password (PASS command)
- `-sasl=<user>:<pass>` — SASL PLAIN authentication credentials
- `-bind=<ip>` — Bind to a specific local IP address
- `-autosendcmd=<cmds>` — Commands to run on connect (semicolon-separated)

### remove

Remove a server and disconnect if connected.

    /server remove <id>

Aliases: del

## Examples

    /server list
    /server add libera irc.libera.chat 6697 -tls
    /server add local 127.0.0.1 6667 -noauto -label=dev
    /server add ircnet irc.ircnet.net 6697 -tls -nick=mynick -sasl=user:pass
    /server add bouncer bnc.example.com 6697 -tls -password=secret -bind=192.168.1.10
    /server remove libera

## See Also

/connect, /disconnect, /set

## Info

# /admin

## Syntax

    /admin [server]

## Description

Request administrative information about the IRC server, typically including the admin's name, email, and other contact details. If a server name is given, the request is forwarded to that server.

## Examples

    /admin
    /admin irc.libera.chat

## See Also

/info, /stats, /time

# /help

## Syntax

    /help [command] [subcommand]

## Description

Show help for commands. With no arguments, lists all commands grouped by category. With a command name, shows detailed usage, subcommands, and examples. With a command and subcommand, shows help for that specific subcommand.

## Examples

    /help
    /help server
    /help server add
    /help items format

## See Also

/set

# /info

## Syntax

    /info [server]

## Description

Request information from the IRC server, such as software version, patch level, and compile date. If a server name is given, the request is forwarded to that server.

## Examples

    /info
    /info irc.libera.chat

## See Also

/admin, /stats, /time, /version

# /links

## Syntax

    /links [remote] [mask]

## Description

List the servers linked to the IRC network. Optionally provide a remote server to query from, and a mask pattern to filter the results.

## Examples

    /links
    /links *.libera.chat
    /links irc.libera.chat *.eu

## See Also

/info, /stats, /lusers

# /list

## Syntax

    /list [pattern]

## Description

Request a list of channels from the server. Optionally filter by a pattern (e.g. `#rust*`).

Results are displayed in the server status buffer as they arrive.

Note: On large networks, `/list` without a filter may return thousands of channels.

## Examples

    /list
    /list #rust*
    /list *linux*

## See Also

/join, /names

# /lusers

## Syntax

    /lusers [mask] [server]

## Description

Request user statistics from the IRC server, including total users, invisible users, servers, operators, and channels. Optionally provide a mask to filter results, and a server name to query a specific server.

## Examples

    /lusers
    /lusers *.fi
    /lusers * irc.libera.chat

## See Also

/stats, /info, /who

# /mentions

Switch to the Mentions buffer — a persistent buffer pinned at the top of the sidebar that aggregates all highlight mentions from all networks.

## Usage

    /mentions

## Description

The Mentions buffer collects every message where your nick is mentioned across all connected networks. Messages are displayed in a scrollable chat view with the format:

    [timestamp] network  #channel nick❯ message text

The network name appears in the nick column, and the channel + sender are shown in the message text.

## Buffer Behavior

- Always first in the buffer list (no number, pinned to top)
- Scrollback: 7 days or 1000 messages, whichever is smaller
- Activity: highlights in the sidebar when new mentions arrive
- Switching to the buffer clears the highlight (standard buffer behavior)

## Configuration

Toggle the mentions buffer on or off:

    /set display.mentions_buffer true    — show the buffer (default)
    /set display.mentions_buffer false   — hide the buffer (mentions still stored in DB)

## Commands

- `/mentions` — switch to the mentions buffer
- `/clear` — when used in the mentions buffer, clears all messages AND deletes all mentions from the database
- `/close` — hides the mentions buffer and sets `display.mentions_buffer false`

## Storage

Mentions are stored in the SQLite database. When the buffer is re-enabled after being disabled, the last 7 days of mentions (up to 1000) are loaded from the database. Old mentions (>7 days) are automatically purged every hour.

## See also

`/set display.mentions_buffer`, `/clear`

# /mode

## Syntax

    /mode [target] [+/-modes] [params]

## Description

Set or query channel or user modes. With no arguments, queries your own user modes. If the first argument starts with `+` or `-`, applies the mode change to the current channel. Otherwise, the first argument is treated as the target.

## Examples

    /mode
    /mode +i
    /mode #linux +o friend
    /mode +nt
    /mode #linux +b *!*@bad.host

## See Also

/op, /deop, /voice, /ban

# /stats

## Syntax

    /stats [type] [server]

## Description

Request statistics from the IRC server. Common stat types include:

- `u` — server uptime
- `m` — command usage counts
- `o` — configured operators
- `l` — connection information

If no type is given, the server may return a summary or help text.

## Examples

    /stats
    /stats u
    /stats o irc.libera.chat

## See Also

/quote

# /time

## Syntax

    /time [server]

## Description

Request the current local time from the IRC server. If a server name is given, the request is forwarded to that server.

## Examples

    /time
    /time irc.libera.chat

## See Also

/info, /stats, /admin

# /version

## Syntax

    /version [nick]

## Description

Without arguments, queries the IRC server version. With a nick, sends a CTCP VERSION request to that user to find out what client they are using. The reply is displayed in the active buffer.

## Examples

    /version                # query server version
    /version someone        # query someone's client version

## See Also

/whois

# /who

## Syntax

    /who <target>

## Description

Send a WHO query to the server. The target can be a channel name, a nick, or a mask pattern.

Returns information about matching users including nick, username, hostname, server, and real name.

## Examples

    /who #linux
    /who nick
    /who *.fi

## See Also

/whois, /whowas, /names

# /whois

## Syntax

    /whois <nick>

## Description

Look up information about a user including their hostname, real name, channels, server, and account status.

## Examples

    /whois friend
    /whois ChanServ

## See Also

/wii, /nick

# /whowas

## Syntax

    /whowas <nick> [count]

## Description

Query the server for historical information about a nick that is no longer connected. Shows the last known username, hostname, and real name.

Optionally specify a count to limit the number of results returned.

## Examples

    /whowas oldnick
    /whowas user 5

## See Also

/whois, /who

# /wii

## Syntax

    /wii <nick>

## Description

Like `/whois` but also includes idle time and signon time. Sends `WHOIS nick nick` to request the idle information from the user's server.

## Examples

    /wii friend

## See Also

/whois, /nick

## Logging

# /log

## Syntax

    /log [status|search] [query]

## Description

Manage persistent chat logs. Messages are stored in a local SQLite database at `~/.repartee/logs/messages.db` with WAL mode for concurrent access.

Only messages that reach the UI are logged — messages filtered by `/ignore`, antiflood, or script `stop()` propagation are never stored.

## Subcommands

### status

Show logging status including message count, database size, and encryption mode.

    /log status

This is the default when no subcommand is given.

### search

Full-text search across logged messages (plain text mode only).

    /log search <query>

Searches within the current buffer's network and channel context. Results show the 20 most recent matches with timestamps.

Search is not available in encrypted mode since ciphertext cannot be indexed.

## Configuration

    [logging]
    enabled = true                 # enable/disable logging
    encrypt = false                # AES-256-GCM encryption (disables search)
    retention_days = 0             # 0 = keep forever
    event_retention_hours = 72     # auto-prune events after 72h (0 = keep forever)
    exclude_types = []             # filter: "message", "action", "notice", "ctcp", "event"

### Encryption

When `encrypt = true`, message text is encrypted with AES-256-GCM using a 256-bit key auto-generated in `~/.repartee/.env`. No password is required — same trust model as irssi logs or SSH keys.

Only the `text` column is encrypted. Network, buffer, nick, timestamp, and type remain queryable for the future web frontend.

### Retention

Set `retention_days` to automatically purge old messages on startup. `0` means keep forever.

### Event retention

`event_retention_hours` controls how long event messages (join/part/quit/nick/kick/mode) are kept. Defaults to 72 hours. Pruning runs on startup and every hour in the background. Only event-type rows are affected — chat messages are never touched.

    /set logging.event_retention_hours 72    # default
    /set logging.event_retention_hours 0     # keep forever

### Excluding Types

Filter specific message types from logging:

    [logging]
    exclude_types = ["event"]  # skip join/part/quit/nick events

This is especially important if you're on many channels. A single QUIT or NICK change fans out to every shared channel — on 70 channels, one quit becomes 35+ log rows. Adding `"event"` to `exclude_types` prevents this bloat.

## Examples

    /log
    /log status
    /log search ssl certificate

## See Also

/set, /ignore

## Media

# /image

## Syntax

    /image [stats|clear|cleanup|debug]

## Description

Manage the image preview cache. Without arguments, shows current status.

All image preview settings are persistent via `/set`:

    /set image_preview.enabled true|false
    /set image_preview.protocol auto|kitty|iterm2|sixel|symbols
    /set image_preview.max_width 0
    /set image_preview.cache_max_mb 100

## Subcommands

### stats

Show cache file count and disk usage.

    /image stats

### clear

Delete all cached images.

    /image clear

### cleanup

Remove cached images that exceed the configured size or age limits (`image_preview.cache_max_mb` and `image_preview.cache_max_days`). Reports the number of files removed and disk space freed.

    /image cleanup

### debug

Show detailed image preview diagnostics including detected protocol, terminal capabilities, font size, environment variables, and tmux passthrough status.

    /image debug

## Examples

    /image
    /image stats
    /image clear
    /image cleanup
    /image debug
    /set image_preview.enabled false
    /set image_preview.protocol kitty

## See Also

/preview, /set

# /preview

## Syntax

    /preview <url>

## Description

Fetches an image URL and displays it as a popup overlay in the terminal. Supports direct image links (jpg, png, gif, webp) and pages with og:image metadata (imgur, imgbb, etc.).

The display protocol is auto-detected based on your terminal: kitty, iTerm2, sixel, or Unicode half-block fallback. Works through tmux with DCS passthrough.

Press any key or click to dismiss the preview.

## Examples

    /preview https://i.imgur.com/abc123.jpg
    /preview https://imgur.com/gallery/xyz

## See Also

/image

## Messaging

# /away

## Syntax

    /away [reason]

## Description

Mark yourself as away with an optional reason message. When someone sends you a private message while you are away, the server will automatically reply with your away reason.

If called without arguments, clears your away status (marks you as back).

## Examples

    /away Gone for lunch
    /away

## See Also

/nick, /msg

# /me

## Syntax

    /me <action>

## Description

Send a CTCP ACTION message to the current channel or query. Displayed as `* nick action` in the chat.

## Examples

    /me waves hello
    /me is away for lunch

## See Also

/msg, /notice

# /msg

## Syntax

    /msg <target> <message>

## Description

Send a private message to a user or channel. For private messages, a query window is automatically opened and focused. Messages sent to channels appear in the channel buffer.

## Examples

    /msg NickServ IDENTIFY mypassword
    /msg friend Hey, what's up?
    /msg #linux Hello everyone

## See Also

/notice, /me

# /nick

## Syntax

    /nick <newnick>

## Description

Change your nickname on the current server. The server may reject the change if the nick is already in use or contains invalid characters.

## Examples

    /nick newnick
    /nick myname_away

## See Also

/whois, /set

# /notice

## Syntax

    /notice <target> <message>

## Description

Send a NOTICE to a user or channel. Notices are typically used for automated replies and should not trigger auto-responses from bots.

## Examples

    /notice friend Check out this link
    /notice #linux Announcement: meeting at 5pm

## See Also

/msg, /me

# /query

## Syntax

    /query <nick> [message]

## Description

Open a private message buffer with a user. If a message is provided, it is sent immediately. The query buffer is created and switched to.

## Examples

    /query alice
    /query bob Hey, how are you?

## See Also

/msg, /close

# /wallops

## Syntax

    /wallops <message>

## Description

Send a message to all connected IRC operators. This is an operator-only command typically used for server-wide announcements among staff.

## Examples

    /wallops Server maintenance in 10 minutes
    /wallops New oper guidelines posted on the wiki

## See Also

/oper, /quote

## Moderation

# /ban

## Syntax

    /ban [mask]
    /ban -a <account>

## Description

Ban a user or hostmask from the current channel.

With no arguments, requests the ban list from the server and displays it as a numbered list. These numbers can be used with `/unban` to remove entries by index.

With a mask argument, sets mode `+b` on the channel. If the argument contains `!` or `@`, it is used as a literal hostmask. Otherwise it is sent as-is (the server typically treats a plain nick as `nick!*@*`).

The `-a` flag creates an account extban (`$a:account`) if the server supports EXTBAN with the account type.

## Examples

    /ban                        Show numbered ban list
    /ban *!*@bad.host.com       Ban a hostmask
    /ban *!*ident@*.isp.net     Ban by ident and host pattern
    /ban -a troll               Account extban ($a:troll)

## See Also

/unban, /kick, /kb, /mode

# /deop

## Syntax

    /deop <nick> [nick2 ...]

## Description

Remove channel operator status (-o) from one or more users in the current channel. You must be a channel operator to use this command.

## Examples

    /deop troublemaker
    /deop user1 user2

## See Also

/op, /devoice, /mode

# /devoice

## Syntax

    /devoice <nick> [nick2 ...]

## Description

Remove voice status (-v) from one or more users in the current channel. You must be a channel operator to use this command.

## Examples

    /devoice user1
    /devoice user1 user2

## See Also

/voice, /deop, /mode

# /ignore

## Syntax

    /ignore [mask] [levels...] [-channels #a,#b]

## Description

Add an ignore rule to suppress messages and events from matching users. Without arguments, lists current ignore rules.

A bare nick pattern (e.g., `troll`) matches the nick only. A pattern containing `!` (e.g., `*!*@bad.host`) matches the full `nick!user@host` mask with wildcard support (`*`, `?`).

Use `-channels` to restrict the ignore to specific channels (comma-separated). Without it, the ignore applies everywhere.

## Levels

    MSGS      Private messages
    PUBLIC    Channel messages
    NOTICES   Notices
    ACTIONS   CTCP ACTIONs (/me)
    JOINS     Join events
    PARTS     Part events
    QUITS     Quit events
    NICKS     Nick change events
    KICKS     Kick events
    CTCPS     CTCP requests and responses
    ALL       All of the above

If no levels are specified, ALL is assumed.

## Examples

    /ignore
    /ignore troll
    /ignore *!*@bad.host.com
    /ignore spammer PUBLIC NOTICES
    /ignore troll ALL -channels #chat,#help

## See Also

/unignore

# /kb

## Syntax

    /kb <nick> [reason]

## Description

Kick and ban a user from the current channel. Looks up the user's ident and host from cached WHOX data to create a proper `*!*ident@host` ban mask, then kicks with the given reason.

Falls back to `nick!*@*` if the user's ident and host are not available (e.g. the server does not support WHOX or userhost-in-names).

The reason defaults to the nick if not provided.

## Examples

    /kb troll
    /kb spammer Enough is enough

## See Also

/kick, /ban, /unban, /mode

# /kick

## Syntax

    /kick <nick> [reason]

## Aliases

    /k

## Description

Kick a user from the current channel. If no reason is given, the user's nick is used as the reason. You must be a channel operator to use this command.

## Examples

    /kick troll
    /kick spammer Stop spamming
    /k troll Get out

## See Also

/ban, /kb, /mode

# /kill

## Syntax

    /kill <nick> [reason]

## Description

Forcefully disconnect a user from the IRC network. This is an operator-only command. If no reason is given, the target's nick is used as the reason.

## Examples

    /kill spammer Spamming is not allowed
    /kill baduser

## See Also

/oper, /kick, /ban

# /op

## Syntax

    /op <nick> [nick2 ...]

## Description

Give channel operator status (+o) to one or more users in the current channel. You must be a channel operator to use this command.

## Examples

    /op friend
    /op user1 user2 user3

## See Also

/deop, /voice, /mode

# /unban

## Syntax

    /unban <number|mask|wildcard> [...]

## Description

Remove one or more bans from the current channel. Accepts numeric references (from the numbered list shown by `/ban`), literal masks, and wildcard patterns that match against stored bans.

Use `/ban` with no arguments first to display the numbered ban list, then `/unban 1 3 5` to remove entries by their index.

Wildcard patterns (`*` and `?`) are matched against the stored ban list. Use `/unban *` to remove all bans from the channel.

Multiple arguments can be given to remove several bans at once.

## Examples

    /unban *                     Remove all bans
    /unban 1                     Remove first entry from ban list
    /unban 2 4 7                 Remove multiple entries by index
    /unban *!*@*.spam.host       Remove all bans matching pattern
    /unban *!*@good.host.com     Remove by literal mask
    /unban 1 *!*@other.net       Mix numeric and wildcard

## See Also

/ban, /kick, /kb, /mode

# /unignore

## Syntax

    /unignore <number|mask>

## Description

Remove an ignore rule by its number (from `/ignore` list) or by the exact mask pattern.

## Examples

    /unignore 1
    /unignore troll
    /unignore *!*@bad.host.com

## See Also

/ignore

# /voice

## Syntax

    /voice <nick> [nick2 ...]

## Description

Give voice status (+v) to one or more users in the current channel. Voiced users can speak in moderated (+m) channels. You must be a channel operator to use this command.

## Examples

    /voice user1
    /voice user1 user2

## See Also

/devoice, /op, /mode

## Other

# /shell

## Syntax

    /shell [open|cmd|close|list] [command]

## Aliases

    /sh

## Description

Open an embedded PTY-backed shell terminal inside Repartee. You get a real terminal experience (zsh, bash, vim, htop) without leaving the IRC client.

Shell buffers appear under a "Shell" group in the sidebar. You can open multiple shells and switch between them with Alt+N.

### Input Mode

When a shell buffer is active, all keyboard input is forwarded to the shell process. To return to IRC command input, press Ctrl+] (the telnet escape convention).

Alt+digit and Alt+Left/Right still work for buffer switching even while in shell input mode. Clicking a buffer in the sidebar also switches away from the shell.

## Subcommands

- `/shell` or `/shell open` — Open a new shell using `$SHELL`
- `/shell cmd <command>` — Open a shell running a specific command (e.g. `/shell cmd htop`)
- `/shell close` — Close the currently active shell buffer (kills the process)
- `/shell list` — List all active shell sessions

If the subcommand is not recognized, it is treated as a command to run (e.g. `/shell htop` is equivalent to `/shell cmd htop`).

## Examples

    /shell
    /sh cmd htop
    /shell cmd vim /etc/hosts
    /shell close
    /shell list

## Notes

- When you type `exit` in a shell, the buffer is automatically closed.
- Shell buffers are not logged to the message database.
- The shell PTY is resized automatically when the terminal window changes size.

## See Also

/close

## Scripts

# /script

## Syntax

    /script [list|load|unload|reload|autoload|template] [name]

## Description

Manage user scripts. Scripts are Lua 5.4 files in `~/.repartee/scripts/` that extend Repartee with custom commands, event hooks, filters, and automation.

Scripts run in a sandboxed Lua environment — `os`, `io`, `loadfile`, `dofile`, and `package` are removed. Each script gets its own isolated environment.

## Subcommands

### list

Show currently loaded scripts with version and description.

    /script list

This is the default when no subcommand is given.

### load

Load a script by name.

    /script load <name>

Looks for `~/.repartee/scripts/<name>.lua`.

### unload

Unload a script. All event handlers, commands, and timers registered by the script are automatically cleaned up. If the script returned a cleanup function from `setup()`, it is called.

    /script unload <name>

### reload

Unload and reload a script.

    /script reload <name>

### autoload

Show or manage scripts that load automatically on startup.

    /script autoload

### template

Create a starter script file with the standard boilerplate.

    /script template

## Autoloading

All `.lua` files in `~/.repartee/scripts/` are loaded automatically on startup.

You can also explicitly list scripts in `config.toml`:

    [scripts]
    autoload = ["auto-away", "spam-filter"]
    debug = false

## Writing Scripts

Scripts are `.lua` files with a `meta` table and a `setup` function:

    meta = {
        name = "my-script",
        version = "1.0",
        description = "What it does",
    }

    function setup(api)
        -- Register event handlers
        api.on("irc.privmsg", function(ev)
            -- handle message
        end)

        -- Register custom commands
        api.command("mycommand", {
            handler = function(args, conn_id) --[[ ... ]] end,
            description = "Does something",
            usage = "/mycommand <arg>",
        })

        -- Optional: return cleanup function
        return function()
            api.log("my-script unloaded")
        end
    end

### Available Events

IRC events: `irc.privmsg`, `irc.action`, `irc.notice`, `irc.join`, `irc.part`, `irc.quit`, `irc.kick`, `irc.nick`, `irc.topic`, `irc.mode`, `irc.invite`, `irc.ctcp_request`, `irc.ctcp_response`, `irc.wallops`

Lifecycle events: `command_input`, `connected`, `disconnected`

### Event Priority

Handlers run in descending priority order. Use priority constants:

- `api.PRIORITY_HIGHEST` (100)
- `api.PRIORITY_HIGH` (75)
- `api.PRIORITY_NORMAL` (50) — default
- `api.PRIORITY_LOW` (25)
- `api.PRIORITY_LOWEST` (0)

Return `true` from a handler to suppress the event.

### Per-Script Config

Access per-script config values at runtime:

    local val = api.config.get("timeout", 300)
    api.config.set("timeout", 600)

Read app-level config with dot-path notation:

    local theme = api.config.app_get("general.theme")

## Examples

    /script list
    /script load auto-away
    /script reload auto-away
    /script unload auto-away
    /script template

## See Also

/set

## Server

# /oper

## Syntax

    /oper <name> <password>

## Description

Authenticate as an IRC operator. Requires valid operator credentials configured on the server. Once authenticated, you gain access to operator commands like /kill and /wallops.

## Examples

    /oper admin secretpass

## See Also

/kill, /wallops

# /quote

## Syntax

    /quote <raw command>

## Description

Send a raw IRC command directly to the server. This is useful for commands not yet implemented, testing, or advanced protocol interaction.

## Aliases

/raw

## Examples

    /quote VERSION
    /raw LUSERS
    /quote PRIVMSG #channel :hello

## See Also

/stats

## Statusbar

# /items

## Syntax

    /items [list|add|remove|move|format|separator|available|reset] [args...]

## Description

Manage the statusbar layout. Add, remove, reorder, and format statusbar items.

## Subcommands

### list

Show current statusbar items with their positions.

    /items list

This is the default when no subcommand is given.

### add

Add an item to the statusbar.

    /items add <item>

### remove

Remove an item from the statusbar.

    /items remove <item>

### move

Move an item to a different position in the statusbar.

    /items move <item> <position>

Position is 1-based (1 = first item).

### format

Set or view the format string for a statusbar item.

    /items format <item> [format_string]

Without a format string, shows the current format.

### separator

Set or view the separator between statusbar items.

    /items separator [string]

Without a string, shows the current separator.

### available

List all available statusbar item types.

    /items available

### reset

Reset statusbar to default items, formats, and separator.

    /items reset

## Available Items

- `time` — Current time
- `nick_info` — Current nick and user modes
- `channel_info` — Channel/buffer name and modes
- `lag` — Server lag measurement
- `active_windows` — Windows with unread activity

## Examples

    /items list
    /items add time
    /items remove lag
    /items move time 1
    /items format time %H:%M
    /items separator  -
    /items available
    /items reset

## See Also

/set