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*buttons*
139	Enable or disable mouse buttons in the UI.  Defaults to true.
140	Has no effect without mouse set to true.
141
142*colors* { ... }
143	Settings for colors of different UI elements.
144
145	Colors can be set either by name ("red"), by number (from 0 to 255, for the
146	default 256 terminal colors; -1 meaning default), or by RGB hex true color
147	(*#*_rrggbb_).
148
149	Colors are set as sub-directives of the main *colors* directive:
150
151```
152colors {
153    prompt green
154}
155```
156
157[[ *Sub-directive*
158:< *Description*
159|  prompt <color>
160:  color for ">"-prompt that appears in command mode
161|  unread <color>
162:  foreground color for unread buffer names in buffer lists
163|  status [...]
164:  foreground color for status event lines (e.g. join, part, nick changes) in buffers, see table below
165|  nicks [...]
166:  color scheme for user nicks, see table below
167
168[[ *status sub-directive*
169:< *Description*
170|  status <color>
171:  show status events with the specified color
172|  status disabled
173:  hide status events
174
175[[ *nicks sub-directive*
176:< *Description*
177|  nicks base
178:  show nicks with 16 different colors (default)
179|  nicks extended
180:  show nicks with 256 different colors
181|  nicks fixed [<others>]
182:  show nicks with a fixed color, optionally specifying the colors for other nicks
183|  nicks self <self>
184:  show self nick with a fixed specified color (can be added along other directives)
185
186*shortcuts* { ... }
187	Settings for custom keyboard shortcuts.
188
189	Shortcuts are defined by `*<key> <action> [<params>...]*` subdirectives:
190
191```
192shortcuts {
193    Alt+k cursor-delete-after
194    Shift+Alt+Page_Up set-editor "/me slaps OP with a large trout"
195}
196```
197
198	Keys are optional modifiers (*Control*/*Shift*/*Alt*/*Super*) and a key name,
199	which can either be a literal character (e.g. *k*) or a name for that key,
200	taken from the XKB key names (on Linux, see *wev* for finding key names,
201	e.g. *Page_Up*, *XF86AudioPlay*).
202
203	A custom shortcut will override any default shortcut for that key.
204
205[[ *action*
206:< *Description*
207|  none
208:  *clears the shortcut, no action*
209|  quit
210:  clear the editor, or type `/quit`
211|  set-editor <text>
212:  set the editor to the passed text, if empty
213|  cursor-start
214:  move the cursor to the beginning of the editor
215|  cursor-end
216:  move the cursor to the end of the editor
217|  redraw
218:  refresh the window
219|  scroll-up
220:  go up in the timeline
221|  scroll-down
222:  go down in the timeline
223|  scroll-next-highlight
224:  go down to the next highlight
225|  scroll-previous-highlight
226:  go up to the next highlight
227|  buffer-next
228:  go to the next buffer
229|  buffer-previous
230:  go to the previous buffer
231|  buffer-next-unread
232:  go to the next unread buffer
233|  buffer-previous-unread
234:  go to the previous unread buffer
235|  cursor-right-word
236:  move the cursor to the next word
237|  cursor-left-word
238:  move the cursor to the previous word
239|  cursor-right
240:  move the cursor to the next character
241|  cursor-left
242:  move the cursor to the previous character
243|  cursor-up
244:  scroll back one line in the editor
245|  cursor-down
246:  scroll forward one line in the editor
247|  cursor-delete-previous-word
248:  delete the previous word in the editor
249|  cursor-delete-next-word
250:  delete the next word in the editor
251|  cursor-delete-previous
252:  delete the previous character in the editor
253|  cursor-delete-next
254:  delete the next character in the editor
255|  cursor-delete-before
256:  delete from the cursor to the beginning of the line
257|  cursor-delete-after
258:  delete from the cursor to the end of the line
259|  search-editor
260:  reverse-search in the editor history
261|  auto-complete
262:  open/select the auto-completion dialog/item
263|  close-overlay
264:  close any open overlay buffer (e.g. search results), and clear any message selection
265|  message-select-previous
266:  select the previous message in the timeline
267|  message-select-next
268:  select the next message in the timeline
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)