/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

/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

/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

/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

/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

/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

/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

/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 ~/.kokoirc/logs.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 ~/.kokoirc/.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 events

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

/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

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

Description

Ban a user or hostmask from the current channel. If a plain nick is given, it's converted to nick!*@*. If the argument contains ! or @, it's used as a literal hostmask.

Examples

/ban troll
/ban *!*@bad.host.com
/ban *!*ident@*.isp.net

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 via USERHOST to create a proper *!*ident@host ban mask, then kicks with the given reason. Falls back to nick!*@* if the lookup times out after 5 seconds.

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 <nick|mask>

Description

Remove a ban from the current channel. If a plain nick is given, it's converted to nick!*@*. If the argument contains ! or @, it's used as a literal hostmask.

Examples

/unban friend
/unban *!*@good.host.com

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|available|load|unload|reload] [name]

Description

Manage user scripts. Scripts are TypeScript files in ~/.kokoirc/scripts/ that extend kokoIRC with custom commands, event hooks, filters, and automation.

Scripts have full access to the IRC client, store, and UI — same trust model as irssi Perl scripts.

Subcommands

list

Show currently loaded scripts with version and description.

/script list

This is the default when no subcommand is given.

available

Show all script files found in ~/.kokoirc/scripts/.

/script available

Loaded scripts are marked with a filled circle (●).

load

Load a script by name or absolute path.

/script load <name>
/script load /path/to/script.ts

When given a name without a path, looks for ~/.kokoirc/scripts/<name>.ts.

unload

Unload a script. All event handlers, commands, and timers registered by the script are automatically cleaned up.

/script unload <name>

reload

Unload and reload a script (cache-busted import).

/script reload <name>

Autoloading

Add script names to config.toml to load them on startup:

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

Writing Scripts

Scripts are .ts files that export a default init function:

import type { KokoAPI, IrcMessageEvent } from "@/core/scripts/types"

export const meta = { name: "my-script", version: "1.0.0", description: "..." }
export const config = { timeout: 300 }  // defaults for [scripts.my-script]

export default function init(api: KokoAPI) {
  // Use api.EventPriority for priority constants (HIGHEST, HIGH, NORMAL, LOW, LOWEST)
  api.on("irc.privmsg", (event: IrcMessageEvent, ctx) => {
    // ctx.stop() prevents lower-priority handlers + built-in store update
  }, api.EventPriority.LOW)

  api.command("mycommand", { handler(args, connId) { /* ... */ }, description: "..." })

  return () => { /* cleanup on unload */ }
}

Import rules: Scripts live outside the project, so @/ path aliases only work with import type (stripped at runtime). For values like EventPriority, use api.EventPriority instead of importing.

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

App events: command_input, connected, disconnected

Per-Script Config

Declare defaults with export const config = {...}. Users override in TOML:

[scripts.auto-away]
timeout = 300
message = "AFK"

Access via api.config.get("timeout", 300).

Examples

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

See Also

/set, /alias

/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