.\" Generated by scdoc 1.11.4
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "senpai" "5" "2026-06-02"
.PP
.SH NAME
.PP
senpai - Configuration file format and settings
.PP
.SH DESCRIPTION
.PP
A senpai configuration file is a scfg file.\&
See https://git.\&sr.\&ht/\(tiemersion/scfg.\&
.PP
Some settings are required, the others are optional.\&
.PP
.SH SETTINGS
.PP
\fBaddress\fR (required)
.RS 4
The address (\fIhost[:port]\fR) of the IRC server.\& senpai uses TLS connections
by default unless you specify \fBtls\fR option to be \fBfalse\fR.\& TLS connections
default to port 6697, plain-text use port 6667.\&
.PP
An optional scheme can be specified (scheme://\fIhost[:port]\fR):
.PP
.PD 0
.IP \(bu 4
irc:// is the implicit default, TLS is enabled or disabled according to
the \fBtls\fR configuration value.\&
.IP \(bu 4
ircs:// enables TLS.\&
.IP \(bu 4
irc+insecure:// disables TLS (plain-text IRC).\&
.IP \(bu 4
ircs+insecure:// enables TLS but skips TLS certificate verification.\& This
protects against passive MITM attacks but not against active MITM attacks.\&
.PD
.PP
.RE
\fBnickname\fR (required)
.RS 4
Your nickname, sent with a \fINICK\fR IRC message.\& It mustn'\&t contain spaces or
colons (\fB:\fR).\&
.PP
.RE
\fBrealname\fR
.RS 4
Your real name, or actually just a field that will be available to others
and may contain spaces and colons.\&  Sent with the \fIUSER\fR IRC message.\&  By
default, the value of \fBnick\fR is used.\&
.PP
.RE
\fBusername\fR
.RS 4
Your username, sent with the \fIUSER\fR IRC message and also used for SASL
authentication.\&  By default, the value of \fBnick\fR is used.\&
.PP
.RE
\fBpassword\fR
.RS 4
Your password, used for SASL authentication.\& See also \fBpassword-cmd\fR.\&
.PP
.RE
\fBpassword-cmd\fR command [arguments.\&.\&.\&]
.RS 4
Alternatively to providing your SASL authentication password directly in
plaintext, you can specify a command to be run to fetch the password at
runtime.\& This is useful if you store your passwords in a separate (probably
encrypted) file using `gpg` or a command line password manager such as
\fIpass\fR or \fIgopass\fR.\& If a \fBpassword-cmd\fR is provided, the value of \fBpassword\fR
will be ignored and the first line of the output of \fBpassword-cmd\fR will be
used for login.\&
.PP
The command and arguments are already quoted by scfg, so there is no need to
additionally quote the whole command string.\& For example:
.PP
.RE
.nf
.RS 4
password-cmd pass "Messaging/irc"
.fi
.RE
.PP
\fBchannel\fR
.RS 4
A space separated list of channel names that senpai will automatically join
at startup and server reconnect.\& This directive can be specified multiple
times.\&
.PP
This directive should not be used when using a bouncer, as the bouncer
already remembers and joins senpai to its saved channels automatically.\&
.PP
.RE
\fBhighlight\fR
.RS 4
A space separated list of keywords that will trigger a notification and a
display indicator when said by others.\& This directive can be specified
multiple times.\&
.PP
By default, senpai will use your current nickname.\&
.PP
.RE
\fBon-highlight-beep\fR
.RS 4
Enable sending the bell character (BEL) when you are highlighted.\&
Defaults to disabled.\&
.PP
.RE
\fBpane-widths\fR { .\&.\&.\& }
.RS 4
Configure the width of various UI panes.\&
.PP
Pane widths are set as sub-directives of the main \fBpane-widths\fR directive:
.PP
.RE
.nf
.RS 4
pane-widths {
    nicknames 16
}
.fi
.RE
.PP
.RS 4
This directive supports the following sub-directives:
.PP
\fBnicknames\fR
.RS 4
The number of cells that the column for nicknames occupies in the
timeline.\& By default, 14.\&
.PP
.RE
\fBchannels\fR
.RS 4
The number of cells that the column for channels occupies on screen.\&
By default, 16.\& Use special value 0 to make the channel list horizontal.\&
If the value is negative, the channel list will be horizontal by default
and will take the positive (opposite) width value when toggled with F7.\&
.PP
.RE
\fBmembers\fR
.RS 4
The number of cells that that the column for the list of channel members
occupies on screen.\& By default, 16.\& Use special value 0 to disable.\&
If the value is negative, the member list will be disabled by default
and will take the positive (opposite) width value when toggled with F8.\&
.PP
.RE
\fBtext\fR
.RS 4
The maximum message text line width for messages, in number of cells.\&
By default, the value is zero, which means that there is no maximum.\&
Useful for keeping a readable line width on large screens.\&
.PP
.RE
.RE
\fBtls\fR
.RS 4
Enable TLS encryption.\&  Defaults to true.\&
.PP
.RE
\fBtypings\fR
.RS 4
Send typing notifications which let others know when you are typing a
message.\& Defaults to true.\&
.PP
.RE
\fBmouse\fR
.RS 4
Enable or disable mouse support.\&  Defaults to true.\&
.PP
.RE
\fBspell-check\fR
.RS 4
Enable spell checking using harper-ls.\& Requires harper-ls to be installed.\&
English only for now.\& Defaults to false.\&
.PP
.RE
\fBcolors\fR { .\&.\&.\& }
.RS 4
Settings for colors of different UI elements.\&
.PP
Colors can be set either by name ("red"), by number (from 0 to 255, for the
default 256 terminal colors; -1 meaning default), or by RGB hex true color
(\fB#\fR\fIrrggbb\fR).\&
.PP
Colors are set as sub-directives of the main \fBcolors\fR directive:
.PP
.RE
.nf
.RS 4
colors {
    prompt green
}
.fi
.RE
.PP
.TS
allbox;l lx
l lx
l lx
l lx
l lx.
T{
\fBSub-directive\fR
T}	T{
\fBDescription\fR
T}
T{
prompt <color>
T}	T{
color for ">"-prompt that appears in command mode
T}
T{
unread <color>
T}	T{
foreground color for unread buffer names in buffer lists
T}
T{
status [.\&.\&.\&]
T}	T{
foreground color for status event lines (e.\&g.\& join, part, nick changes) in buffers, see table below
T}
T{
nicks [.\&.\&.\&]
T}	T{
color scheme for user nicks, see table below
T}
.TE
.sp 1
.TS
allbox;l lx
l lx
l lx.
T{
\fBstatus sub-directive\fR
T}	T{
\fBDescription\fR
T}
T{
status <color>
T}	T{
show status events with the specified color
T}
T{
status disabled
T}	T{
hide status events
T}
.TE
.sp 1
.TS
allbox;l lx
l lx
l lx
l lx
l lx.
T{
\fBnicks sub-directive\fR
T}	T{
\fBDescription\fR
T}
T{
nicks base
T}	T{
show nicks with 16 different colors (default)
T}
T{
nicks extended
T}	T{
show nicks with 256 different colors
T}
T{
nicks fixed [<others>]
T}	T{
show nicks with a fixed color, optionally specifying the colors for other nicks
T}
T{
nicks self <self>
T}	T{
show self nick with a fixed specified color (can be added along other directives)
T}
.TE
.sp 1
\fBshortcuts\fR { .\&.\&.\& }
.RS 4
Settings for custom keyboard shortcuts.\&
.PP
Shortcuts are defined by `\fB<key> <action> [<params>.\&.\&.\&]\fR` subdirectives:
.PP
.RE
.nf
.RS 4
shortcuts {
    Alt+k cursor-delete-after
    Shift+Alt+Page_Up set-editor "/me slaps OP with a large trout"
}
.fi
.RE
.PP
.RS 4
Keys are optional modifiers (\fBControl\fR/\fBShift\fR/\fBAlt\fR/\fBSuper\fR) and a key name,
which can either be a literal character (e.\&g.\& \fBk\fR) or a name for that key,
taken from the XKB key names (on Linux, see \fBwev\fR for finding key names,
e.\&g.\& \fBPage_Up\fR, \fBXF86AudioPlay\fR).\&
.PP
A custom shortcut will override any default shortcut for that key.\&
.PP
.RE
.TS
allbox;l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fBaction\fR
T}	T{
\fBDescription\fR
T}
T{
none
T}	T{
\fBclears the shortcut, no action\fR
T}
T{
quit
T}	T{
clear the editor, or type `/quit`
T}
T{
set-editor <text>
T}	T{
set the editor to the passed text, if empty
T}
T{
cursor-start
T}	T{
move the cursor to the beginning of the editor
T}
T{
cursor-end
T}	T{
move the cursor to the end of the editor
T}
T{
redraw
T}	T{
refresh the window
T}
T{
scroll-up
T}	T{
go up in the timeline
T}
T{
scroll-down
T}	T{
go down in the timeline
T}
T{
scroll-next-highlight
T}	T{
go down to the next highlight
T}
T{
scroll-previous-highlight
T}	T{
go up to the next highlight
T}
T{
buffer-next
T}	T{
go to the next buffer
T}
T{
buffer-previous
T}	T{
go to the previous buffer
T}
T{
buffer-next-unread
T}	T{
go to the next unread buffer
T}
T{
buffer-previous-unread
T}	T{
go to the previous unread buffer
T}
T{
cursor-right-word
T}	T{
move the cursor to the next word
T}
T{
cursor-left-word
T}	T{
move the cursor to the previous word
T}
T{
cursor-right
T}	T{
move the cursor to the next character
T}
T{
cursor-left
T}	T{
move the cursor to the previous character
T}
T{
cursor-up
T}	T{
scroll back one line in the editor
T}
T{
cursor-down
T}	T{
scroll forward one line in the editor
T}
T{
cursor-delete-previous-word
T}	T{
delete the previous word in the editor
T}
T{
cursor-delete-next-word
T}	T{
delete the next word in the editor
T}
T{
cursor-delete-previous
T}	T{
delete the previous character in the editor
T}
T{
cursor-delete-next
T}	T{
delete the next character in the editor
T}
T{
cursor-delete-before
T}	T{
delete from the cursor to the beginning of the line
T}
T{
cursor-delete-after
T}	T{
delete from the cursor to the end of the line
T}
T{
search-editor
T}	T{
reverse-search in the editor history
T}
T{
auto-complete
T}	T{
open/select the auto-completion dialog/item
T}
T{
close-overlay
T}	T{
close any open overlay buffer (e.\&g.\& search results)
T}
T{
toggle-channel-list
T}	T{
show/hide the vertical channel list
T}
T{
toggle-member-list
T}	T{
show/hide the vertical member list
T}
T{
send
T}	T{
send the contents of the editor
T}
T{
buffer <number>|\fIlast\fR
T}	T{
go the 0-indexed numbered buffer, or the last one
T}
.TE
.sp 1
\fBdebug\fR
.RS 4
Advanced.\&
Dump all sent and received data to the home buffer, useful for debugging.\&
Defaults to false.\&
.PP
.RE
\fBtransient\fR
.RS 4
Advanced.\&
Run an ephemeral instance without disk reads/writes (except for the initial
configuration).\& Can be useful for public instances.\&
Defaults to false.\&
.PP
.RE
\fBlocal-integrations\fR
.RS 4
Advanced.\&
Enables integrations with the local system (e.\&g.\& notifications through
DBus).\& Can be useful to disable on systems planned to be used through SSH.\&
Defaults to true.\&
.PP
.RE
\fBon-highlight-path\fR
.RS 4
Advanced.\& senpai will notify you by default without the need for a custom
highlight script.\&
Alternative path to a shell script to be executed when you are highlighted.\&
By default, senpai looks for a highlight shell script at
$XDG_CONFIG_HOME/senpai/highlight.\& If no file is found at that path, and an
alternate path is not provided, highlight command execution is disabled.\&
.PP
If unset, $XDG_CONFIG_HOME defaults to \fB\(ti/.\&config/\fR.\&
.PP
Before the highlight script is executed, the following environment
variables are populated:
.PP
Shell scripts MUST ENSURE VARIABLES appear QUOTED in the script file,
OR YOU WILL BE OPEN TO SHELL INJECTION ATTACKS.\& Shell scripts must also
ensure characters like '\&*'\& and '\&?\&'\& are not expanded.\&
.PP
.RE
.TS
allbox;l lx
l lx
l lx
l lx
l lx.
T{
\fBEnvironment variable\fR
T}	T{
\fBDescription\fR
T}
T{
BUFFER
T}	T{
buffer where the message appeared
T}
T{
HERE
T}	T{
equals 1 if \fIBUFFER\fR is the current buffer, 0 otherwise
T}
T{
MESSAGE
T}	T{
content of the message
T}
T{
SENDER
T}	T{
nickname of the sender
T}
.TE
.sp 1
.RS 4
Note: when passing those to \fBnotify-send\fR(1), some notification daemons use
\fB\e\fR for escape sequences in the body, which causes \fB\e\fR to disappear from the
message or triggers unintended side-effects (like newlines).\&
.PP
To get around this, you can double the backslash with the following snippet:
.PP
.RE
.nf
.RS 4
#!/bin/sh
escape() {
	printf "%s" "$1" | sed \&'s#\\\\#\\\\\\\\#g\&'
}

notify-send "[$BUFFER] $SENDER" "$(escape "$MESSAGE")"
.fi
.RE
.PP
.SH EXAMPLES
.PP
A minimal configuration file to connect to Libera.\&Chat as "Guest123456":
.PP
.nf
.RS 4
address irc\&.libera\&.chat
nickname Guest123456
.fi
.RE
.PP
A more advanced configuration file that fetches a password from an external
program, changes the width of some panes, and enables more colors for user
nicks:
.PP
.nf
.RS 4
address irc\&.libera\&.chat
nickname Guest123456
username senpai
realname "Guest von Lenon"
password-cmd gopass show irc/guest # use your favorite CLI password solution here
channel "#rahxephon"
pane-widths {
	nicknames 10
	channels 16
	members 16
}
colors {
	nicks extended
}
shortcuts {
    Alt+k cursor-delete-after
}
.fi
.RE
.PP
.SH SEE ALSO
.PP
\fBsenpai\fR(1)