diff options
Diffstat (limited to 'catgirl.1')
| -rw-r--r-- | catgirl.1 | 449 |
1 files changed, 257 insertions, 192 deletions
diff --git a/catgirl.1 b/catgirl.1 index 32eb365..44ed1bd 100644 --- a/catgirl.1 +++ b/catgirl.1 @@ -1,4 +1,4 @@ -.Dd May 29, 2022 +.Dd May 22, 2024 .Dt CATGIRL 1 .Os . @@ -8,7 +8,7 @@ . .Sh SYNOPSIS .Nm -.Op Fl KRelqv +.Op Fl Relqv .Op Fl C Ar copy .Op Fl H Ar hash .Op Fl I Ar highlight @@ -46,9 +46,9 @@ The .Nm IRC client -provides a curses interface -for TLS-only -Internet Relay Chat. +provides a curses interface for +Internet Relay Chat +over TLS. The only required option is .Fl h , the host name to connect to. @@ -62,7 +62,8 @@ in to view the list of .Sx COMMANDS and -.Sx KEY BINDINGS . +.Sx KEY BINDINGS +in this manual. . .Pp Options can be loaded from files @@ -78,50 +79,65 @@ unless the path starts with .Ql \&./ or .Ql \&../ . -Files and flags listed later -on the command line -take precedence over -those listed earlier. +For example, +a configuration file at +.Pa ~/.config/catgirl/tilde +can be loaded by running +.Ql catgirl tilde . . .Pp Each option is placed on a line, and lines beginning with .Ql # are ignored. +An optional +.Ql = +may appear +between an option and its value. The options are listed below following their corresponding flags. +Flags and options in files are processed +in the order they appear on the command line, +so later values override earlier values. . .Bl -tag -width Ds -.It Fl C Ar util | Cm copy No = Ar util -Set the utility used by -.Ic /copy . +.It Fl C Ar util | Cm copy Ar util +Set the utility used by the +.Ic /copy +command. Subsequent .Cm copy -options append arguments to -.Ar util . -The URL to copy is provided to -.Ar util -on standard input. +options add arguments +to the utility. +The URL to copy is provided +to the utility on standard input. The default is the first available of .Xr pbcopy 1 , .Xr wl-copy 1 , -.Xr xclip 1 , +.Xr xclip 1 +or .Xr xsel 1 . . -.It Fl H Ar seed,bound | Cm hash No = Ar seed,bound -Set the initial seed -of the nick and channel -color hash function -and the maximum IRC color value -produced by the function. -The default is 0,75. -To use only colors from -the 16-color terminal set, +.It Fl H Ar seed,bound | Cm hash Ar seed,bound +Set the seed for choosing +nick and channel colours +and the maximum IRC colour value +that will be chosen. +Changing the seed +will randomize the chosen colours, +in case you don't like the ones +chosen for yourself or your crush. +.Pp +The default is 0,75, +which uses colours +in the 256-colour terminal set. +To use only colours +from the 16-colour terminal set, use 0,15. -To disable nick and channel colors, +To disable nick and channel colours, use 0,0. . -.It Fl I Ar pattern | Cm highlight No = Ar pattern +.It Fl I Ar pattern | Cm highlight Ar pattern Add a case-insensitive message highlight pattern, which may contain .Ql * , @@ -132,60 +148,51 @@ wildcards as in .Xr glob 7 . The format of the pattern is as follows: .Bd -ragged -offset indent +.\" FIXME: there's really no reason !user@host should be required .Ar nick Ns Op Ar !user@host Op Ar command Op Ar channel Op Ar message .Ed .Pp The commands which can be matched are: -.Sy INVITE , -.Sy JOIN , -.Sy NICK , -.Sy NOTICE , -.Sy PART , -.Sy PRIVMSG , -.Sy QUIT , -.Sy SETNAME . -. -.It Fl K | Cm kiosk -Disable the -.Ic /copy , -.Ic /debug , -.Ic /exec , -.Ic /join , -.Ic /list , -.Ic /msg , -.Ic /open , -.Ic /part , -.Ic /query , -.Ic /quote -commands. -Replace the username -with a hash of its original value. +.Sy invite , +.Sy join , +.Sy nick , +.Sy notice , +.Sy part , +.Sy privmsg , +.Sy quit , +.Sy setname . +.Pp +For example, +to highlight whenever your crush +joins your favourite channel: +.Pp +.Dl highlight crush!*@* join #channel . -.It Fl N Ar util | Cm notify No = Ar util +.It Fl N Ar util | Cm notify Ar util Send notifications using a utility. Subsequent .Cm notify -options append arguments to -.Ar util . +options add arguments +to the utility. The window name and message -are provided to -.Ar util +are provided to the utility as two additional arguments, appropriate for .Xr notify-send 1 . . -.It Fl O Ar util | Cm open No = Ar util -Set the utility used by -.Ic /open . +.It Fl O Ar util | Cm open Ar util +Set the utility used by the +.Ic /open +command. Subsequent .Cm open -options append arguments to -.Ar util . -The URL to open is provided to -.Ar util -as an argument. +options add arguments +to the utility. +The URL to open is provided +to the utility as an additional argument. The default is the first available of -.Xr open 1 , +.Xr open 1 +or .Xr xdg-open 1 . . .It Fl R | Cm restrict @@ -201,58 +208,75 @@ option, and viewing this manual with .Ic /help . . -.It Fl S Ar host | Cm bind No = Ar host +.It Fl S Ar host | Cm bind Ar host Bind to source address .Ar host when connecting to the server. -To connect from any address -over IPv4 only, +To connect from any IPv4 address, use 0.0.0.0. -To connect from any address -over IPv6 only, +To connect from any IPv6 address, use ::. . -.It Fl T Ns Oo Ar format Oc | Cm timestamp Op = Ar format -Show timestamps by default, -in the specified -.Xr strftime 3 -.Ar format . -The format string may contain -raw IRC formatting codes. -The default format is -.Qq \&%X . +.It Fl T Ns Oo Ar format Oc | Cm timestamp Op Ar format +Show timestamps by default. +The optional +.Ar format +string is interpreted by +.Xr strftime 3 . +The string may contain +raw IRC formatting codes, +if you can figure out +how to enter them. . -.It Fl a Ar user : Ns Ar pass | Cm sasl-plain No = Ar user : Ns Ar pass -Authenticate as -.Ar user -with -.Ar pass -using SASL PLAIN. +.It Fl a Ar user : Ns Ar pass | Cm sasl-plain Ar user : Ns Ar pass +Authenticate with NickServ +during connection using SASL PLAIN. +.Nm +will disconnect +if authentication fails. Leave .Ar pass -blank to prompt for the password. +blank to prompt for the password when +.Nm +starts. . -.It Fl c Ar path | Cm cert No = Ar path -Load the TLS client certificate from -.Ar path . -The -.Ar path -is searched for in the same manner -as configuration files. -If the private key is in a separate file, -it is loaded with -.Cm priv . -With -.Cm sasl-external , -authenticate using SASL EXTERNAL. -Certificates can be generated with -.Fl g . +.It Fl c Ar path | Cm cert Ar path +Connect using a TLS client certificate +loaded from +.Ar path , +which is searched for +in the same manner as configuration files. +If the private key +is in a separate file, +additionally specify it with the +.Cm priv +option. +.Pp +To use this certificate +to authenticate to NickServ +using CertFP, +use the +.Cm sasl-external +option. +See +.Sx Configuring CertFP . +.Pp +Client certificates +can be generated with the +.Fl g +flag. . .It Fl e | Cm sasl-external -Authenticate using SASL EXTERNAL, -also known as CertFP. -The TLS client certificate is loaded with -.Cm cert . +Authenticate to NickServ +during connection using CertFP +via SASL EXTERNAL. +.Nm +will disconnect +if authentication fails. +The client certificate +must be specified with the +.Cm cert +option. See .Sx Configuring CertFP . . @@ -262,11 +286,11 @@ Generate a TLS client certificate using and write it to .Ar path . . -.It Fl h Ar host | Cm host No = Ar host -Connect to +.It Fl h Ar host | Cm host Ar host +Connect to the IRC server .Ar host . . -.It Fl i Ar pattern | Cm ignore No = Ar pattern +.It Fl i Ar pattern | Cm ignore Ar pattern Add a case-insensitive message ignore pattern, which may contain .Ql * , @@ -281,56 +305,69 @@ The format of the pattern is as follows: .Ed .Pp The commands which can be matched are: -.Sy INVITE , -.Sy JOIN , -.Sy NICK , -.Sy NOTICE , -.Sy PART , -.Sy PRIVMSG , -.Sy QUIT , -.Sy SETNAME . +.Sy invite , +.Sy join , +.Sy nick , +.Sy notice , +.Sy part , +.Sy privmsg , +.Sy quit , +.Sy setname . +.Pp +Visibility of ignored messages +can be toggled using +.Ic M-- +and +.Ic M-+ . . -.It Fl j Ar channels Oo Ar keys Oc | Cm join No = Ar channels Oo Ar keys Oc +.It Fl j Ar channels Oo Ar keys Oc | Cm join Ar channels Oo Ar keys Oc Join the comma-separated list of .Ar channels with the optional comma-separated list of channel .Ar keys . +No spaces may appear in either list. . -.It Fl k Ar path | Cm priv No = Ar priv -Load the TLS client private key from -.Ar path . -The -.Ar path -is searched for in the same manner -as configuration files. +.It Fl k Ar path | Cm priv Ar path +Load the TLS client private key +for a certificate loaded with the +.Cm cert +option from +.Ar path , +which is search for +in the same manner as configuration files. . .It Fl l | Cm log -Log chat events to files in paths -.Pa $XDG_DATA_HOME/catgirl/log/network/channel/YYYY-MM-DD.log . +Log messages to files in +.Pa $XDG_DATA_HOME/catgirl/log +.Po +usually +.Pa ~/.local/share/catgirl/log +.Pc . +Directories are created +for each network and channel, +and files are created for each date +in the format +.Pa YYYY-MM-DD.log . . -.It Fl m Ar mode | Cm mode No = Ar mode -Set the user -.Ar mode . +.It Fl m Ar modes | Cm mode Ar modes +Set user modes as soon as possible +after connecting. . -.It Fl n Ar nick Oo Ar ... Oc | Cm nick No = Ar nick Oo Ar ... Oc -Set nickname to -.Ar nick . -The default nickname is -the value of the environment variable +.It Fl n Ar nick Oo Ar ... Oc | Cm nick Ar nick Oo Ar ... Oc +Set the nickname with optional fallbacks, +should one nick be unavailable. +Each nick is treated as a highlight word. +The default nickname is the value of .Ev USER . -Additional space-separated nicks -will be tried in order -if the first is not available, -and all nicks -are treated as highlight words. . .It Fl o -Print the server certificate chain -to standard output in PEM format -and exit. +Connect to the server +only to obtain its certificate chain +and write it to standard output +in PEM format. . -.It Fl p Ar port | Cm port No = Ar port -Connect to +.It Fl p Ar port | Cm port Ar port +Connect to the IRC server on .Ar port . The default port is 6697. . @@ -339,17 +376,27 @@ Raise the default message visibility threshold for new windows, hiding general events (joins, quits, etc.). +The threshold can be lowered with +.Ic M-- . . -.It Fl r Ar real | Cm real No = Ar real -Set realname to -.Ar real . -The default realname is the same as the nickname. +.It Fl r Ar real | Cm real Ar real +Set the +.Dq realname +which appears in +.Ic /whois . +The default is the same as the nickname. +This is a good place to add your pronouns. . -.It Fl s Ar name | Cm save No = Ar name -Save and load the contents of windows from +.It Fl s Ar name | Cm save Ar name +Persist windows and their scrollback +in a file called .Ar name in -.Pa $XDG_DATA_DIRS/catgirl , +.Pa $XDG_DATA_DIRS/catgirl +.Po +usually +.Pa ~/.local/share/catgirl +.Pc , or an absolute or relative path if .Ar name starts with @@ -358,39 +405,50 @@ starts with or .Ql \&../ . . -.It Fl t Ar path | Cm trust No = Ar path -Trust the self-signed certificate -loaded from -.Ar path -and disable server name verification. -The -.Ar path -is searched for in the same manner -as configuration files. +.It Fl t Ar path | Cm trust Ar path +Trust the self-signed certificate in +.Ar path , +which is searched for +in the same manner as configuration files. +Server name verification is also disabled. See .Sx Connecting to Servers with Self-signed Certificates . . -.It Fl u Ar user | Cm user No = Ar user -Set username to -.Ar user . -The default username is the same as the nickname. +.It Fl u Ar user | Cm user Ar user +Set the username. +This is almost entirely irrelevant, +except that it's more likely to remain stable, +and +.Nm +uses it to choose nick colours. +The default is the same as the nickname. . .It Fl v | Cm debug -Log raw IRC messages to the +Log raw IRC protocol to the .Sy <debug> -window +window, as well as standard error if it is not a terminal. . -.It Fl w Ar pass | Cm pass No = Ar pass -Log in with the server password -.Ar pass . +.It Fl w Ar pass | Cm pass Ar pass +Connect using a server password. Leave .Ar pass -blank to prompt for the password. +blank +.Po +using an +.Ql = +.Pc +to prompt for the password when +.Nm +starts. .El . .Ss Configuring CertFP +CertFP allows you to +authenticate with NickServ during connection +using a TLS client certificate +rather than your account password. .Bl -enum .It Generate a new TLS client certificate: @@ -398,32 +456,34 @@ Generate a new TLS client certificate: $ catgirl -g ~/.config/catgirl/example.pem .Ed .It -Connect to the server using the certificate: +Connect to the server using the certificate +by adding the following configuration: .Bd -literal -offset indent -cert = example.pem -# or: $ catgirl -c example.pem +cert example.pem .Ed .It -Identify with services or use -.Cm sasl-plain , +Identify with NickServ, then add the certificate fingerprint to your account: .Bd -literal -offset indent /ns CERT ADD .Ed .It -Enable SASL EXTERNAL +Enable SASL EXTERNAL in your configuration to require successful authentication when connecting (not possible on all networks): .Bd -literal -offset indent -cert = example.pem +cert example.pem sasl-external -# or: $ catgirl -e -c example.pem .Ed .El . .Ss Connecting to Servers with Self-signed Certificates +If connecting to a server fails +with a certificate verification error +due to a self-signed certificate, +it needs to be trusted manually. .Bl -enum .It Connect to the server @@ -436,8 +496,7 @@ Configure .Nm to trust the certificate: .Bd -literal -offset indent -trust = example.pem -# or: $ catgirl -t example.pem +trust example.pem .Ed .El . @@ -445,13 +504,13 @@ trust = example.pem The .Nm interface is split -into three areas. +into three main areas. . .Ss Status Line The top line of the terminal shows window statuses. Only the currently active window -and windows with activity are listed. +and windows with activity are shown. The status line for a window might look like this: .Bd -literal -offset indent @@ -462,7 +521,8 @@ The number on the left is the window number. Following it may be one of .Ql - , -.Ql + , +.Ql + +or .Ql ++ , as well as .Ql = . @@ -478,11 +538,11 @@ indicates the number of unread messages. The number following .Ql ~ indicates how many lines -are below the scroll position. +are below the current scroll position. An .Ql @ indicates that there is unsent input -in the window's +waiting in the window's .Sx Input Line . .Pp .Nm @@ -512,7 +572,11 @@ with the nick between hyphens. .Pp Blank lines are inserted into the chat -as unread markers. +as unread markers +whenever there are messages +in a window that is not active +or the terminal is not focused +(in some terminal emulators). .Pp While scrolling, the most recent 5 lines of chat @@ -649,6 +713,9 @@ use the option. .It Ic /move Oo Ar name Oc Ar num Move the named or current window to number. +.It Ic /o ... +Alias of +.Ic /open . .It Ic /open Op Ar count Open each of .Ar count @@ -922,9 +989,7 @@ The .Nm client exits 0 if requested by the user, -.Dv EX_UNAVAILABLE -(69) -if the connection is lost, +69 if the connection is lost, and >0 if any other error occurs. . .Sh EXAMPLES |