1senpai(5)
  2
  3# NAME
  4
  5senpai - Configuration file format and settings
  6
  7# DESCRIPTION
  8
  9A senpai configuration file is a scfg file.
 10See https://git.sr.ht/~emersion/scfg.
 11
 12Some settings are required, the others are optional.
 13
 14# SETTINGS
 15
 16*address* (required)
 17	The address (_host[:port]_) of the IRC server. senpai uses TLS connections
 18	by default unless you specify *tls* option to be *false*. TLS connections
 19	default to port 6697, plain-text use port 6667.
 20
 21	An optional scheme can be specified (scheme://_host[:port]_):
 22
 23	- irc:// is the implicit default, TLS is enabled or disabled according to
 24	  the *tls* configuration value.
 25	- ircs:// enables TLS.
 26	- irc+insecure:// disables TLS (plain-text IRC).
 27	- ircs+insecure:// enables TLS but skips TLS certificate verification. This
 28	  protects against passive MITM attacks but not against active MITM attacks.
 29
 30*nickname* (required)
 31	Your nickname, sent with a _NICK_ IRC message. It mustn't contain spaces or
 32	colons (*:*).
 33
 34*realname*
 35	Your real name, or actually just a field that will be available to others
 36	and may contain spaces and colons.  Sent with the _USER_ IRC message.  By
 37	default, the value of *nick* is used.
 38
 39*username*
 40	Your username, sent with the _USER_ IRC message and also used for SASL
 41	authentication.  By default, the value of *nick* is used.
 42
 43*password*
 44	Your password, used for SASL authentication. See also *password-cmd*.
 45
 46*password-cmd* command [arguments...]
 47	Alternatively to providing your SASL authentication password directly in
 48	plaintext, you can specify a command to be run to fetch the password at
 49	runtime. This is useful if you store your passwords in a separate (probably
 50	encrypted) file using `gpg` or a command line password manager such as
 51	_pass_ or _gopass_. If a *password-cmd* is provided, the value of *password*
 52	will be ignored and the first line of the output of *password-cmd* will be
 53	used for login.
 54
 55	The command and arguments are already quoted by scfg, so there is no need to
 56	additionally quote the whole command string. For example:
 57
 58```
 59password-cmd pass "Messaging/irc"
 60```
 61
 62*channel*
 63	A space separated list of channel names that senpai will automatically join
 64	at startup and server reconnect. This directive can be specified multiple
 65	times.
 66
 67	This directive should not be used when using a bouncer, as the bouncer
 68	already remembers and joins senpai to its saved channels automatically.
 69
 70*highlight*
 71	A space separated list of keywords that will trigger a notification and a
 72	display indicator when said by others. This directive can be specified
 73	multiple times.
 74
 75	By default, senpai will use your current nickname.
 76
 77*on-highlight-beep*
 78	Enable sending the bell character (BEL) when you are highlighted.
 79	Defaults to disabled.
 80
 81*pane-widths* { ... }
 82	Configure the width of various UI panes.
 83
 84	Pane widths are set as sub-directives of the main *pane-widths* directive:
 85
 86```
 87pane-widths {
 88    nicknames 16
 89}
 90```
 91
 92	This directive supports the following sub-directives:
 93
 94	*nicknames*
 95		The number of cells that the column for nicknames occupies in the
 96		timeline. By default, 14.
 97
 98	*channels*
 99		The number of cells that the column for channels occupies on screen.
100		By default, 16. Use special value 0 to make the channel list horizontal.
101		If the value is negative, the channel list will be horizontal by default
102		and will take the positive (opposite) width value when toggled with F7.
103
104	*members*
105		The number of cells that that the column for the list of channel members
106		occupies on screen. By default, 16. Use special value 0 to disable.
107		If the value is negative, the member list will be disabled by default
108		and will take the positive (opposite) width value when toggled with F8.
109
110	*text*
111		The maximum message text line width for messages, in number of cells.
112		By default, the value is zero, which means that there is no maximum.
113		Useful for keeping a readable line width on large screens.
114
115*tls*
116	Enable TLS encryption.  Defaults to true.
117
118*show-typings*
119	Show some text  in the status bar to let you know when others are typing.
120	Defaults to true.
121
122*typings*
123	Send typing notifications which let others know when you are typing a
124	message. Defaults to true.
125
126*mouse*
127	Enable or disable mouse support.  Defaults to true.
128
129*quitmessages*
130	Enable or disable showing quit and part messages.  Defaults to false.
131
132*nick-prefix*
133	Show the speaker's channel-membership prefix (e.g. *@* for an operator,
134	*+* for a voiced user) next to their nick on each message in a channel
135	buffer. Only the highest-priority prefix is shown. Has no effect in
136	private query buffers. Defaults to false.
137
138*colors* { ... }
139	Settings for colors of different UI elements.
140
141	Colors can be set either by name ("red"), by number (from 0 to 255, for the
142	default 256 terminal colors; -1 meaning default), or by RGB hex true color
143	(*#*_rrggbb_).
144
145	Colors are set as sub-directives of the main *colors* directive:
146
147```
148colors {
149    prompt green
150}
151```
152
153[[ *Sub-directive*
154:< *Description*
155|  prompt <color>
156:  color for ">"-prompt that appears in command mode
157|  unread <color>
158:  foreground color for unread buffer names in buffer lists
159|  status [...]
160:  foreground color for status event lines (e.g. join, part, nick changes) in buffers, see table below
161|  nicks [...]
162:  color scheme for user nicks, see table below
163
164[[ *status sub-directive*
165:< *Description*
166|  status <color>
167:  show status events with the specified color
168|  status disabled
169:  hide status events
170
171[[ *nicks sub-directive*
172:< *Description*
173|  nicks base
174:  show nicks with 16 different colors (default)
175|  nicks extended
176:  show nicks with 256 different colors
177|  nicks fixed [<others>]
178:  show nicks with a fixed color, optionally specifying the colors for other nicks
179|  nicks self <self>
180:  show self nick with a fixed specified color (can be added along other directives)
181
182*shortcuts* { ... }
183	Settings for custom keyboard shortcuts.
184
185	Shortcuts are defined by `*<key> <action> [<params>...]*` subdirectives:
186
187```
188shortcuts {
189    Alt+k cursor-delete-after
190    Shift+Alt+Page_Up set-editor "/me slaps OP with a large trout"
191}
192```
193
194	Keys are optional modifiers (*Control*/*Shift*/*Alt*/*Super*) and a key name,
195	which can either be a literal character (e.g. *k*) or a name for that key,
196	taken from the XKB key names (on Linux, see *wev* for finding key names,
197	e.g. *Page_Up*, *XF86AudioPlay*).
198
199	A custom shortcut will override any default shortcut for that key.
200
201[[ *action*
202:< *Description*
203|  none
204:  *clears the shortcut, no action*
205|  quit
206:  clear the editor, or type `/quit`
207|  set-editor <text>
208:  set the editor to the passed text, if empty
209|  cursor-start
210:  move the cursor to the beginning of the editor
211|  cursor-end
212:  move the cursor to the end of the editor
213|  redraw
214:  refresh the window
215|  scroll-up
216:  go up in the timeline
217|  scroll-down
218:  go down in the timeline
219|  scroll-next-highlight
220:  go down to the next highlight
221|  scroll-previous-highlight
222:  go up to the next highlight
223|  buffer-next
224:  go to the next buffer
225|  buffer-previous
226:  go to the previous buffer
227|  buffer-next-unread
228:  go to the next unread buffer
229|  buffer-previous-unread
230:  go to the previous unread buffer
231|  cursor-right-word
232:  move the cursor to the next word
233|  cursor-left-word
234:  move the cursor to the previous word
235|  cursor-right
236:  move the cursor to the next character
237|  cursor-left
238:  move the cursor to the previous character
239|  cursor-up
240:  scroll back one line in the editor
241|  cursor-down
242:  scroll forward one line in the editor
243|  cursor-delete-previous-word
244:  delete the previous word in the editor
245|  cursor-delete-next-word
246:  delete the next word in the editor
247|  cursor-delete-previous
248:  delete the previous character in the editor
249|  cursor-delete-next
250:  delete the next character in the editor
251|  cursor-delete-before
252:  delete from the cursor to the beginning of the line
253|  cursor-delete-after
254:  delete from the cursor to the end of the line
255|  search-editor
256:  reverse-search in the editor history
257|  auto-complete
258:  open/select the auto-completion dialog/item
259|  close-overlay
260:  close any open overlay buffer (e.g. search results), and clear any message selection
261|  message-select-previous
262:  select the previous message in the timeline
263|  message-select-next
264:  select the next message in the timeline
265|  message-react
266:  mark the selected message as reacting to using the editor, reacting twice will remove
267|  message-reply
268:  copy the selected message as replying to using the editor
269|  message-copy
270:  copy the selected message to the system clipboard
271|  toggle-channel-list
272:  show/hide the vertical channel list
273|  toggle-member-list
274:  show/hide the vertical member list
275|  send
276:  send the contents of the editor
277|  buffer <number>|_last_
278:  go the 0-indexed numbered buffer, or the last one
279
280*debug*
281	Advanced.
282	Dump all sent and received data to the home buffer, useful for debugging.
283	Defaults to false.
284
285*transient*
286	Advanced.
287	Run an ephemeral instance without disk reads/writes (except for the initial
288	configuration). Can be useful for public instances.
289	Defaults to false.
290
291*local-integrations*
292	Advanced.
293	Enables integrations with the local system (e.g. notifications through
294	DBus). Can be useful to disable on systems planned to be used through SSH.
295	Defaults to true.
296
297*on-highlight-path*
298	Advanced. senpai will notify you by default without the need for a custom
299	highlight script.
300	Alternative path to a shell script to be executed when you are highlighted.
301	By default, senpai looks for a highlight shell script at
302	$XDG_CONFIG_HOME/senpai/highlight. If no file is found at that path, and an
303	alternate path is not provided, highlight command execution is disabled.
304
305	If unset, $XDG_CONFIG_HOME defaults to *~/.config/*.
306
307	Before the highlight script is executed, the following environment
308	variables are populated:
309
310	Shell scripts MUST ENSURE VARIABLES appear QUOTED in the script file,
311	OR YOU WILL BE OPEN TO SHELL INJECTION ATTACKS. Shell scripts must also
312	ensure characters like '\*' and '?' are not expanded.
313
314[[ *Environment variable*
315:< *Description*
316|  BUFFER
317:  buffer where the message appeared
318|  HERE
319:  equals 1 if _BUFFER_ is the current buffer, 0 otherwise
320|  MESSAGE
321:  content of the message
322|  SENDER
323:  nickname of the sender
324
325	Note: when passing those to *notify-send*(1), some notification daemons use
326	*\\* for escape sequences in the body, which causes *\\* to disappear from the
327	message or triggers unintended side-effects (like newlines).
328
329	To get around this, you can double the backslash with the following snippet:
330
331```
332#!/bin/sh
333escape() {
334	printf "%s" "$1" | sed 's#\\\\#\\\\\\\\#g'
335}
336
337notify-send "[$BUFFER] $SENDER" "$(escape "$MESSAGE")"
338```
339
340# EXAMPLES
341
342A minimal configuration file to connect to Libera.Chat as "Guest123456":
343
344```
345address irc.libera.chat
346nickname Guest123456
347```
348
349A more advanced configuration file that fetches a password from an external
350program, changes the width of some panes, and enables more colors for user
351nicks:
352
353```
354address irc.libera.chat
355nickname Guest123456
356username senpai
357realname "Guest von Lenon"
358password-cmd gopass show irc/guest # use your favorite CLI password solution here
359channel "#rahxephon"
360pane-widths {
361	nicknames 10
362	channels 16
363	members 16
364}
365colors {
366	nicks extended
367}
368shortcuts {
369    Alt+k cursor-delete-after
370}
371```
372
373# SEE ALSO
374
375*senpai*(1)