/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

/alias

Syntax

/alias [[-]name] [body]

Description

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

With no arguments, lists all defined aliases. With just a name, shows that alias's body. With -name, removes the alias. With name and body, defines or replaces the alias.

Template variables:

• $0-$9 — positional arguments
• $* — all arguments
• $C — current channel name
• $N — current nick
• $S — current server label
• $T — current buffer name

Cannot override built-in commands.

Examples

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

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

See Also

/reload, /server, /items

/unalias

Syntax

/unalias <name>

Description

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

Examples

/unalias ns

See Also

/alias

/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

/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)
• -noauto — Don't auto-connect on startup
• -notlsverify — Skip TLS certificate verification
• -bind=<ip> — Bind to local IP (vhost)
• -nick=<nick> — Server-specific nick override
• -label=<name> — Display name
• -password=<pass> — Server password (saved to .env)
• -sasl=<user>:<pass> — SASL auth (saved to .env)
• -autosendcmd=<cmds> — Commands to run on connect, before autojoin (must be last flag)

Autosendcmd uses erssi-style syntax: commands separated by ;, with WAIT <ms> for delays. $N is replaced with your nick.

/server add libera irc.libera.chat:6697 -tls -autosendcmd=MSG NickServ identify pass; WAIT 2000; MODE $N +i

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 libera irc.libera.chat:6697 -tls -sasl=user:pass
/server add local 127.0.0.1:6667 -noauto -label=dev
/server remove libera

See Also

/connect, /disconnect, /set

/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

/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

/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

/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

/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
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.

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

/image

Syntax

/image [stats|clear]

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

Examples

/image
/image stats
/image clear
/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

/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

/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 (*, ?).

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 bot CTCPS -channels #help,#support

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]

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

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

/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

/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

/items

Syntax

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

Description

Manage the statusbar layout. Add, remove, reorder items and customize their format strings. Use /items available to see all possible items and their format variables.

Subcommands

list

Show current statusbar items with their positions and formats.

/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>

Aliases: del

move

Move an item to a new position.

/items move <item> <position>

Position is 1-based.

format

View or set the format string for an item.

/items format <item> [format_string]

Format variables: $win, $activity, $nick, $modes, $name, $lag, $time.

Aliases: fmt

separator

View or set the separator string between items.

/items separator [string]

Aliases: sep

available

List all available statusbar items and their default formats.

/items available

Shows which items are currently active and which are unused.

reset

Reset statusbar to default items, formats, and separator.

/items reset

Examples

/items list
/items add clock
/items remove lag
/items move clock 1
/items format window_name [$win] $name
/items separator  |
/items available
/items reset

See Also

/set