After seeing various people in #WeeChat still struggle with setting up (or rather configuring) their WeeChat client to their liking (even though there's a nice QuickStart document), I decided to write my own post to get you started with this awesome chat client which has become my favourite IRC client.
However, since people's preferences differ (luckily! otherwise the world would be a boring place!), I would also suggest you have a look at these other tutorials and blogs about WeeChat:
The installation of packages part assumes you are running Debian or a Debian-based Linux distribution such as Ubuntu. Package names and installation commands may vary depending on the distribution you are using.
Required (and optional) packages
To ensure you have *all* packages required for installing WeeChat along with all its plugins, run:
Cloning the official git repository and compiling and installing WeeChat using CMake
Once all those packages are installed, you can compile WeeChat with the following oneliner, which should clone the WeeChat source from the official git repository into /usr/local/src/weechat (you should ensure you have write access to its parent directory) and will install the compiled WeeChat files into /usr/local:
WEECHAT_SOURCE_DIR=/usr/local/src/weechat && WEECHAT_TARGET_DIR=/usr/local && mkdir -p $WEECHAT_SOURCE_DIR/.. && git clone https://github.com/weechat/weechat.git $WEECHAT_SOURCE_DIR && cd $WEECHAT_SOURCE_DIR && mkdir -p build && cd build && cmake .. -DPREFIX=$WEECHAT_TARGET_DIR -DCMAKE_BUILD_TYPE=Debug -DENABLE_DOC=OFF && make && sudo make install
Personally I use /usr/local/weechat as my WEECHAT_TARGET_DIR, but that would also entail adding the /usr/local/weechat/bin directory to your $PATH, while /usr/local/bin tends to already be included. If you need to make PATH adjustments since your terminal can't find the weechat executable binary, then have a look at this document describing what the PATH environment variable is and how to (permanently) set it..
Running WeeChat
Once everything is installed, you should be able to run WeeChat by running this command: weechat
Updating WeeChat
You can also fairly easily update weechat again. I personally use the following bash script I have saved in ~/bin/update_weechat:
#!/bin/bash
WEECHAT_SOURCE_DIR=/usr/local/src/weechat && WEECHAT_TARGET_DIR=/usr/local && cd $WEECHAT_SOURCE_DIR && git reset --hard HEAD && cd build && cmake .. -DPREFIX=$WEECHAT_TARGET_DIR -DCMAKE_BUILD_TYPE=Debug -DENABLE_DOC=OFF && make && sudo make instal
It will always ensure any changes you might've made to your WeeChat source dir are undone by resetting to the HEAD of the git repository, so make sure that any chances you've made to the source are `git stash`'ed ;-)
Once that has compiled properly, you can upgrade your running WeeChat session from within WeeChat with:
/upgrade
Configuring your terminal
So, before we get started to configuring WeeChat, let's make sure our terminal is properly set up so we don't run into any strange display issues.
Let's have a closer look at each of these commands:
$TERM
Let's first check the TERM environment variable, to make sure it is the right one for displaying the 256 colours that WeeChat supports: echo $TERM
Ideally this should say something like
xterm-256color(as mine returns),
rxvt-unicode-256color,
rxvt-256color,
putty-256color. Or, if you are already inside a terminal multiplexer such as GNU/Screen or tmux, screen-256color.
If it doesn't, I suggest you read the WeeChat F.A.Q.: How can I use 256 colors in WeeChat? to help you fix this issue if you want to be able to use more than 16 colours.
UTF-8
I'm a great fan of using Unicode (and utf-8 in particular) everywhere I can. Why? Because it makes it much easier to see what everyone's writing when we all use the same encoding, and Unicode has enough space for most (if not all?) character sets available.
That aside, let's just say that it's best to run WeeChat with utf-8 support enabled. So, make sure you pick a terminal emulator which has UTF-8 support by itself, and make sure you have enabled it. I can't really go into the details of every terminal emulator application out there, so instead I'll just link to a few online docs that I know of:
iTerm2's Documentation (set the right default $TERM (xterm-256color) via Preferences > Profiles > Terminal > Report Terminal Type) (set the right encoding ("Unicode (UTF-8)") via Preferences > Profiles > Terminal > Character encoding)
([View menu] > Set Encoding > Unicode (utf8))
Locale
One of the requirements is that your terminal needs to be using a UTF-8 locale. So, let's look at which locale are set in your current terminal: locale
As you can see in the terminal example output (for Ubuntu) displayed above it displays a bunch of LC_ and LANG variables that are set to en_GB.UTF-8:
The most important part here is whether the variables are defined at all (at least LANG/LANGUAGE and LC_ALL as far as I know), and if they have a .UTF-8 value.
If they don't or use something like .iso88591, .roman8, C, or POSIX, you probably want to look into changing your locale to one of the .UTF-8 ones.
If something's wrong with your setup, I can't really help you set up your locale for you, so you'll have to do some research for yourself. However, the following links might be helpful:
The last thing to check is to see whether WeeChat is linked to the libncursesw library, which adds support to WeeChat for wide characters. While it might not be necessary to have WeeChat linked against it, it can be handy to check if it is: ldd `which weechat` | grep libncursesw
If it returns something like: libncursesw.so.5 => /lib/libncursesw.so.5 (0x00002b7809152000)
then that is a good sign!
If it returns nothing, you might want to install its development library and recompile WeeChat, just to be sure.
On Ubuntu-based Linux distributions you could do this with: sudo apt-get install libncursesw5-dev.
Even if it is missing, it doesn't need to be a bad thing. If you don't see any strange characters while using WeeChat, then it's probably not needed. If you do, then you have something you could look into. ;-)
On IRC you are bound to see ascii art which uses obscure characters in the unicode character set, and which rely on the font being of a fixed width / monospaced. Therefor it is wise to make sure you are using a font in your terminal that was a wide support for glyphs. My favourite font is DejaVu Sans Mono. You can download DejaVu Sans Mono here. Another favourite is Lucida Console. A longer list of recommended fonts is as follows:
UTF-8 support can be enabled by putting set-window-option -g utf8 on # utf8 support into your .tmux.conf tmux config file.
If you intend to keep WeeChat running in your background, for instance when you run it on a remote SSH connection, I recommend running WeeChat in a terminal multiplexer, such as GNU Screen or tmux. For this guide I'll assume you are running it in tmux.
To easily start and/or reattach to a tmux session you have running specifically for WeeChat, I recommend using this code snippet:
If you want, you can put this in an alias in your .bashrc, or in an executable bash file placed (preferably in a dir that's mentioned in your $PATH).
It will try to attach to a tmux session named 'weechat-tutorial' (feel free to change this name) and if it can't find one, it will start it for you.
As a final test, let's ensure the $TERM is still correct:
echo $TERM
If this shows screen-256color then you are all set!
Which brings us to the next section, starting and setting up WeeChat!
Running WeeChat
Yes, I spent quite some time on making you check your terminal first, but.
We are ready to start running WeeChat now!
Checking for 256 colours in WeeChat
Okay, I lied. :P Before we start WeeChat, let's just check first if it displays the 256 colours correctly: weechat -c
As you can see, for me it shows a nice table of 256 coloured numbers, ranging from 000 (black) to 255 (white). The first 16 are the ones WeeChat uses for its default named colour aliases. Beside the 256 colours, it also shows that my $TERM is screen-256color, that it supports 256 colours, has support for 32767 colour pairs, but can't change colours (not quite sure myself what this last feature does though and how to change it to yes though; probably some ncurses feature).
If it doesn't show all the 256 colours, but just 8 or 16 instead, I suggest you go back to the previous sections to check if you missed something, or check the WeeChat F.A.Q.: How can I use 256 colors in WeeChat?.
Starting weechat
Right, let's start WeeChat. The application was originally called weechat-curses, probably because it allowed for non-curses frontends to the weechat core to be created as well. At some point the executable got renamed to just 'weechat' for clarity. An alias might also be created automatically for backwards 'compatibility'.
As you can see in the example above I've also specified the argument -d ~/.weechat-tutorial which specifies where WeeChat will store its config files. I did this so it wouldn't disturb the config files for my working WeeChat which stores its config files in the default location, ~/.weechat.
So, let's fire it up: weechat
There it is, WeeChat, in its glorious appearance! Glorious? Well… perhaps not yet, but it will be once we are done with it!
A closer look
Let's have a closer look at what is shown on it, shall we?
It shows which version we are running, which is WeeChat 0.4.0-rc2 apparently, and when it was last compiled. I guess I should've updated from the git repository before starting this tutorial. I'll fix that soon enough. ;-)
Default bars
It also tells us that several bars have been created.
Input bar
The input bar is the bar in which you will be typing in all your commands. By default it has window as its type, which makes it show up in every WeeChat window. While I prefer this behaviour, some might prefer a single root input bar, so I'll show you later on how to achieve that too.
Title bar
The title bar shows the title of the buffer which is displayed in the window. Because bars can have a background, it's also nice way to visually separate channels from one another when you've split windows.
Status bar
The status bar is shown below the contents of the current buffer, but above the input bar (by default at least). If for instance you'd like to have the status bar shown above the chat area, you could move it with: /set weechat.bar.status.position top
Nicklist bar
The last bar that was created is the nicklist. This bar displays the nicks of everyone in the channel you are in. Which mouse support enabled, you should be able to scroll through it. I'll go deeper into this later on.
Resetting default bar(s)
If you made a mistake with one or more default bars, you can easily restore them with the /bar default command. This command will only restore missing bars; it won't override existing bars. So, if you want to restore a default bar because you screwed up some settings, then you first have to delete the bar.
Let's say you want to restore the default nicklist, then you can type:
/bar del nicklist
/bar default nicklist
If you want to restore all bars to their default state, then use:
/bar del -all
/bar default
Settings
Some console clients might require you to change all your settings in the config files, but WeeChat strongly discourages this as it would require manual reloading of the config files. Instead, WeeChat comes with the /set command which not only allows you to change your settings directly from within WeeChat, it also allows you to search your currently configured settings.
Looking up settings
Remember that nicklist I mentioned? Let's have a closer look at the options this bar has. /set *nicklist*
This command will show all the settings that have 'nicklist' in them. The * wildcard before and after the text indicates that it doesn't matter what text is before or after the keyword. For my unconfigured WeeChat the following results were shown:
It specifies some colours for the various states of a nickname (weechat.color.nicklist_*), whether colours should be used in the nicklist at all (irc.look.color_nicks_in_nicklist) and the various properties of the nicklist bar (weechat.bar.nicklist.*).
If we would've just wanted WeeChat to show the nicklist bar settings, the following command could've been used instead: /set weechat.bar.nicklist.*
Closer look at bar settings
Looking at the settings we see you can specify the background colour, the colour for the bar delimiter, the foreground (text) colour, 'conditions', how it should be filled with items, if it should be hidden, what bar items are shown in it, where it should be positioned (on the right of the chat area), what its drawing priority is, whether the bar separator is enabled, what its size should be, as well as what its maximum size may be (in case of it being auto-sized by setting the size to 0), and finally, what kind of bar type it is.
Changing settings
Let's change the background colour of the status bar; make it dark gray instead of the dark blue. For this we'll also have to use the /set command, but now we also have to specify a second argument, namely the value: /set weechat.bar.status.color_bg darkgray
The effect should be instant. Feel free to try out a couple of other colours (you should have 256 of them at your disposition!) till you found the one you like.
The /help command
For any command or option/setting in WeeChat there is (or at least should be) help information. These texts, usually very helpful, can be retrieved via the /help command.
Getting an overview of all commands and their descriptions
Going through a list of commands can be quite useful every now and then, for instance to see if there's some new command you hadn't heard of before.
/help -list
/help or /help -list
This command by itself will show you an overview of all the commands WeeChat has help info for. Useful if you are looking for a specific command but can't quite remember the name of.
/help -listfull
I suggest to also have a look at the output of: /help -listfull
which gives you the same list, but now with short descriptions for each of the commands.
Looking up help info for a setting
Are you curious about one of the options? Need some more help for it? Well, you are in luck! WeeChat has a built-in help for all its settings! Let's say we want to know more about the weechat.bar.nicklist.color_delim setting: /help weechat.bar.nicklist.color_delim
It shows the option name, the description (default delimiter color for bar), what kind of value type it expects (color), and the values that are allowed (any of the WeeChat basic colour names, or an (extended) terminal colour number, or a colour alias.), it also shows the default and current value.
For completeness sake I've also included the help text for the help command itself, so you can see that the help command is useful for any setting and any command WeeChat has!
Tab Completion
Don't feel like typing so much? Then get used to using the Tab key to complete the commands you type! WeeChat offers 2 types of completion: partial and full completion. By default WeeChat performs full completions; meaning it will find the first setting/command/name your text matches, and complete it fully.
By changing the weechat.completion.partial_completion-* options you can change this behaviour to a partial completion; meaning it will try to complete your keyword as much as it can till it matches multiple options.
complete_next and complete_previous
With default keybindings, Tab will complete to the next option available as it's bound to /input complete_next, while the Shift+Tab combination will try to complete to the previous available option because it's set to use /input complete_previous. The /input complete_previous command also tries to achieve this by doing a partial completion if you haven't already triggered a regular completion; you might want to use this to your advantage.
Without completion: do a partial completion, with pending completion: complete with previous completion.
Example of difference between full and partial completion
Let's say a channel has FiXato and FiXatNo in it.
Using full completion pressing F followed by the Tab will complete to FiXato.
However, with partial completion it will complete to FiXat and then beep, and show you the possible completion options in your status bar (or where you have placed the completion bar item.).
Completion settings
Of course the completion behaviour is also configurable in WeeChat. For instance:
weechat.completion.base_word_until_cursor
if completion in the middle of a word should be completion at the cursor, or the next space
weechat.completion.default_template
the order in which completion results are presented
weechat.completion.nick_add_space
whether spaces need to be inserted after completing a nick
weechat.completion.nick_completer
whether characters need to be inserted after completing a nick
weechat.completion.nick_ignore_chars
which characters in a nick should be ignored
weechat.completion.partial_completion_*
when partial completion should be done by default
weechat.completion.partial_completion_alert
if an alert (beep) should be given on a partial completion
See weechat.completion.* settings for an overview of all the WeeChat completion options available.
Mouse support
While WeeChat(-curses) is a console-based chat client, that doesn't mean it has no mouse support at all. If your terminal emulator supports (xterm-) mouse reporting, then you can make use of your mouse to control more and more parts of WeeChat. It can for instance be used to switch between windows, or to control the buffers.pl or buflist list. It can also be used to insert nicks from your nicklist, or even open query windows from the nicklist.
How to enable mouse support
Sound great huh? So how to enable this feature? It's easy: /mouse enable
This will change the weechat.look.mouse setting to 'on'.
If you want to see what each mouse command does as you trigger it, you can toggle debugging of mouse commands with: /debug mouse Debug enabled for mouse (normal)
Clicking somewhere in the screen will now for instance show:
Want to extend WeeChat with your own scripts written in your favourite scripting language? Or use one of the hundreds of user-contributed scripts? Read on and learn how!
Script Plugins
WeeChat is very extensible. It has support for various plugins, which are C programmes which can call WeeChat functions defined in an interface. Basically this allows you to extend WeeChat with extra low-level functionality, such as support for various scripting languages.
Various WeeChat plugins allow you to write your own scripts for WeeChat in languages such as Perl, Python, Ruby, Lua, TCL and Scheme/Guile, through which you can add functionality to WeeChat.
There are several ways of managing the plethora of scripts that are available. This section will describe them briefly.
Manually
As with just about everything in WeeChat, you can install and remove scripts manually.
You need to download the scripts into <$WeeChatHomedir>/<$PluginType>/, where $WeeChatHomedir is the directory where all your WeeChat configs are stored (~/.weechat by default) and $PluginType is the name of the plugin through which the script needs to be loaded.
So, if you use the default WeeChat config directory, and you are installing the buffers.pl (Perl) script, then you need to download the file to ~/.weechat/perl/ to be able to load the script.
If you want the script to be auto-loaded, you should create a symlink in the <$WeeChatHomedir>/<$PluginType>/autoload/ directory:
ln -s ../buffers.pl ~/.weechat/perl/autoload/
Once the file(s) are in place, you can load them through the appropriate plugin's command, for instance to load the buffers script, use: /perl load perl/buffers.pl
Unloading scripts can be done through the plugin's unload command, for instance to unload the buffers script: /perl unload buffers
As you can see, you only need the script name for this command.
To list all the Perl scripts, you can use: /perl list or /perl listfull
You can also load all the scripts in the autoload directory with the 'autoload' command for each plugin, for instance: /python autoload
As well as reload a specific script: /perl reload buffers
or all scripts in the plugin's autoload directory:
/ruby reload
The above commands work for every script plugin, so just replace perl with python, ruby, lua or whichever script plugin you have installed and loaded.
Through /script (Plugin)
Downloading and loading scripts manually is timeconsuming and a bit cumbersome though, that's why FlashCode created the Script plugin. This plugin adds support for the new /script command which allows you to load scripts regardless of their scripting language through a single /script command. Apart from that, it also adds a new buffer which will be opened if you issue the /script command with no arguments/parameters:
Titlebar
The /script buffer's title bar shows quite a lot of information help texts such as shortcuts. Let's have a closer look:
234/234: this shows the number of scripts listed, as well as the total of number of scripts in the repository
(filter: *): the current active filter. By typing (part of) a word in the input bar followed by enter, you can filter the list of scripts to only those that match your keyword. By default no filtering is used, which is indicated by an asterisk.
Sort: p,n: this indicates the order of sorting on the list. By default this means the list is sorted first by popularity and next by name. This sort order can be changed via the script.look.sort setting. See /help script.look.sort for all possible keys to sort by.
A list of possible key-combinations.
For instance Alt+i (or i followed by Enter) will install the currently selected script. Alt+r will remove the selected script.
'Holding' scripts is also possible, which will prevent those scripts from being upgraded when using the /script upgrade command as well as prevents them from being removed.
q followed by Enter will close the scripts buffer.
$ followed by Enter will refresh the list.
s: followed by a comma separated list of sort-keys and Enter will change the sort order and adjust script.look.sort.
* followed by Enter will reset the filter.
With mouse enabled (/mouse enable) you can select scripts with the left mouse button and install them with the right mouse button.
Scripts list
The list itself shows a couple of columns. All these columns are configurable through the script.look.columns setting, but I'll describe the default order of columns:
The first column can contain an asterisk, indicating the script is a popular script, as well as various flags which indicate if the script is installed, autoloaded, Held, running or has a New version available.
The second column contains the name of the script, as well as the script's language extension.
Next is the version number of the script that is currently installed.
The purple column contains the version numbers of the scripts that are offered through the script repository.
The date displayed is the date at which the script was last updated in the script repository.
The short description of the script follows this date.
Finally, the tags assigned to the scripts are shown in the last column.
As you can see my version of beep.pl is outdated (indicated by a different version number, as well as the N flag), but that I have also held the version I have (because it has personal changes that I need to merge with the current version and submitted to the WeeChat script repository).
I have also installed buffers.pl, but it isn't running yet.
Through /weeget script (Pre-0.3.9)
The /script plugin was introduced in WeeChat 0.3.9. Before that we had to use the weeget.py script if we wanted to manage our scripts. The script still exists, but /script is quite a bit more versatile, so I suggest you upgrade to the latest version of WeeChat. If for some reason you can't, then here's a list of (self-explanatory) useful weeget commands:
/weeget list list all the scripts that you currently have installed
/weeget list list all the scripts in the official repository
/weeget list notify list all the scripts in the official repository that match the text 'notify' or have 'notify' as tag.
/weeget install buffers.pl install the buffers.pl script from the official repository
/weeget remove buffers.pl remove the buffers.pl script
/weeget check check if there are local scripts that need upgrading
/weeget upgrade upgrade all your local scripts that have a newer version in the repository.
Managing Servers
By default WeeChat only comes configured to connect to freenode, but you'll probably want to connect to various other IRC networks. In this section you can learn how to add, delete and edit IRC networks.
How to add an IRC network?
Let's first have a look at how we can add another IRC network/server connection to WeeChat. The official WeeChat quickstart manual mentions the /server command, so let's have a look at the /help server command:
[irc] /server list|listfull [<server>]
add <server> <hostname>[/<port>] [-temp] [-<option>[=<value>]] [-no<option>]
copy|rename <server> <new_name>
del|keep <server>
deloutq|jump|raw
list, add or remove IRC servers
list: list servers (without argument, this list is displayed)
listfull: list servers with detailed info for each server
add: create a new server
server: server name, for internal and display use
hostname: name or IP address of server, with optional port (default: 6667), many addresses can be separated by a comm
temp: create temporary server (not saved)
option: set option for server (for boolean option, value can be omitted)
nooption: set boolean option to 'off' (for example: -nossl)
copy: duplicate a server
rename: rename a server
keep: keep server in config file (for temporary servers only)
del: delete a server
deloutq: delete messages out queue for all servers (all messages WeeChat is currently sending)
jump: jump to server buffer
raw: open buffer with raw IRC data
Examples:
/server listfull
/server add oftc irc.oftc.net/6697 -ssl -autoconnect
/server add oftc6 irc6.oftc.net/6697 -ipv6 -ssl
/server add freenode2 chat.eu.freenode.net/6667,chat.us.freenode.net/6667
/server add freenode3 irc.freenode.net -password=mypass
/server copy oftc oftcbis
/server rename oftc newoftc
/server del freenode
/server deloutq
So, to add the Chat4All IRC Network (servers: eu.chat4all.org, us.chat4all.org, irc.chat4all.org) with SSL port 6697, and setting it to autoconnect as well to verify the SSL, we have to use: /server add Chat4All us.chat4all.org/6697,eu.chat4all.org/6697,irc.chat4all.org/6697 -autoconnect -ssl -ssl_verify irc: server Chat4All created
Now that we have a configuration for this network, we can connect to it with /connect Chat4All but as you'll probably see, it will fail because of an SSL error:
Chat4All -- | irc: connecting to server us.chat4all.org/6697 (SSL)...
Chat4All -- | gnutls: connected using 2048-bit Diffie-Hellman shared secret exchange
Chat4All =!= | gnutls: peer's certificate is NOT trusted
Chat4All =!= | gnutls: peer's certificate issuer is unknown
Chat4All -- | gnutls: receiving 1 certificate
Chat4All -- | - certificate[1] info:
Chat4All -- | - subject `C=NL,ST=Noord-Brabant,L=Den Bosch,O=Chat4All,OU=Chat4All IRC,CN=*.chat4all.org,EMAIL=jeroen@wierda.com', issuer `C=NL,ST=Noord-Brabant,L=Den Bosch,O=Chat4All,OU=Chat4All IRC,CN=chat4all.org,EMAIL=jeroen@wierda.com', RSA key 4096 bits, signed using RSA-SHA1, activated `2012-09-20 20:00:41 UTC', expires `2013-09-20 20:00:41 UTC', SHA-1 fingerprint `3dc41c41d0ae2ef99363e31969dd38410b52c74c'
Chat4All =!= | irc: TLS handshake failed
Chat4All =!= | irc: error: Error in the certificate.
Feel free to stop the reconnection attempts with /disconnect or /disconnect Chat4All
Oh no! A certificate error for the network! What now?
So, what does the above error message tell us? gnutls: peer's certificate is NOT trusted gnutls: peer's certificate issuer is unknown
The former means that the certificate that's offered by Chat4All isn't trusted, and the latter means that the issuer of the certificate is unknown (and thus not trusted either). Chat4All's SSL certificates page mentions they are using self-signed certificates, which explains why WeeChat doesn't trust them by default. Luckily, Chat4All's wiki has a page that describes how to import Chat4All's CA into WeeChat.
Checking for, and updating the trusted certificate authorities files.
Let's first find out where WeeChat is currently looking for the CA (certificate authorities) file, which defines which CAs are trusted: /set weechat.network.gnutls_ca_file
For me this returned: weechat.network.gnutls_ca_file = "/etc/ssl/certs/ca-certificates.crt"
As we'll want to add our own trusted CA certificates to this file (and probably don't have write access to this file), we'll change this setting so it points to a file in our WeeChat home directory: /set weechat.network.gnutls_ca_file %h/ssl/trusted_CAs.crt
Since this file probably doesn't exist yet, we'll have to copy the server's CA file here as well, so let's open another command shell and do so: mkdir -p ~/.weechat/ssl/ cp /etc/ssl/certs/ca-certificates.crt ~/.weechat/ssl/trusted_CAs.crt
(Assuming your WeeChat configuration/homedir is located in the default location of ~/.weechat)
Retrieving and merging the Chat4All CA certificate.
With the existing trusted CAs file in place, we can download Chat4All's certificate authority file: curl https://www.chat4all.org/ircd-certificates/chat4all-ca.pem -o ~/.weechat/ssl/chat4all-ca.pem
Afterwards we want to verify that it hasn't been altered by checking that the SHA512 sum matches the one mentioned on the website: sha512sum ~/.weechat/ssl/chat4all-ca.pem 4ad04a5ac6eb9e599403e1af99f38792a23ec9e90149ae744eb4088da14aded7cc0cbe0ffa63a9c33b9f63321ef3749f2193f0faa56233d0ded43890ea2c177b ~/.weechat/ssl/chat4all-ca.pem
Now we can merge it with the existing trusted_CAs.crt file by concatenating it: cat ~/.weechat/ssl/chat4all-ca.pem >> ~/.weechat/ssl/trusted_CAs.crt
Reconnecting to Chat4All
If you try to connect to the network now, it should connect normally without errors: /reconnect Chat4All
By adding the CA certificate of Chat4All we now trust any certificate signed with this CA cert. If you don't want to trust the CA, but only the server's certificate, you can also use the Chat4All server certificate instead.
Let's change freenode's settings
The default settings of freenode might allow you to connect without problems, but perhaps you want to change some of the settings, for instance to use an SSL connection instead. So, let's see what settings WeeChat has for the freenode server: /set *freenode*
Remember that you can use /help on each of the settings for more information about the setting, for instance: /help irc.server.freenode.addresses
Let's switch this connection over to SSL! First we have to change the port we will connect to: /set irc.server.freenode.addresses chat.freenode.net/6697
Of course SSL needs to be enabled too, and we want the certificate to be verified: /set irc.server.freenode.ssl on/set irc.server.freenode.ssl_verify on
The WeeChat F.A.Q. item "How can I connect to freenode server using SSL?" also mentions that the dhkey_size needs to be set to 1024: /set irc.server.freenode.ssl_dhkey_size 1024
Auto-join channels on freenode
We also want to autojoin the channels #weechat and #weechat-offtopic, so let's also add those: /set irc.server.freenode.autojoin #weechat,#weechat-offtopic
Auto-identify for your registered nickname on freenode
Since freenode supports SASL authentication, you can use this to identify for your registered nickname.
dh-blowfish is a SASL mechanism, so let's set it as default SASL mechanism: /set irc.server_default.sasl_mechanism dh-blowfish
Now you can also set your registered nickname and password for freenode: /set irc.server.freenode.sasl_username "ReplaceThisWithYourRegisteredNickname"/set irc.server.freenode.sasl_password "ReplaceThisWithYourNickname'sPassword"
Now you should be all set to /connect freenode or /reconnect freenode.
Deleting a network/server:
If you no longer want an IRC network/server listed, then you can delete it with the /server del command, for instance to delete the just-configured Chat4All network: /server del Chat4All
Renaming a network/server:
Let's say that instead of deleting the Chat4All network from our configuration, we want to rename it to c4a, then you can use: /server rename Chat4All c4a
Suggested settings
This section will describe a couple of settings I personally quite like:
Expand title and input bars over multiple lines
By default the title and input bars will only fill a single line because their size is set to 1, however, you can quite easily extend this to 2 or more lines in case it needs more space than a single line offers.
Set the maximum number of lines to 2 for the title bar and 3 for the input bar: /set weechat.bar.title.size_max 2 /set weechat.bar.input.size_max 3
Set the size (number of lines) to auto (0) for the title and input bars: /set weechat.bar.title.size 0 /set weechat.bar.input.size 0
Suggested / My keybinds
This section will describe a couple of keybinds I personally quite like. It overrides some of the Default WeeChat Key bindings, so be careful.
Note that I use /input grab_key_command(meta+k) and /input grab_key(which I assigned myself to meta+Shift+k) a lot to get the correct WeeChat key descriptions for the keyboard shortcuts / key combinations, as these might differ between the various terminal emulators.
Most likely this will show: /key bind meta-ctrl-? /input delete_previous_word and will allow you to delete the previous word with Alt+Backspace
Grab key with meta shift+k
/key bind meta-K /input grab_key
The default keybind meta-k (lowercase) will insert the key description, as well as the command the key is bound to. This new keybind meta-K (uppercase) will only insert the key description, useful if you don't care if the keyboard combination is already bound to some other command.
Switch between windows with CTRL + cursor keys
/key bind Escshift+kCTRL+↑ /window up
/key bind Escshift+kCTRL+↓ /window down
/key bind Escshift+kCTRL+← /window left
/key bind Escshift+kCTRL+→ /window right
Please note that CTRL+→ and CTRL+← are bound by default to move between the next and previous words.
Also note that CTRL+↑ and CTRL+↓ are bound by default to go through the previous and next global history items.
However, personally I prefer to have these simple keyboard shortcuts bound to window switching as I have a bunch of vertical and horizontal window splits.
Go to next and previous word with alt + left/right cursor keys
Please note that Alt+→ and Alt+← are bound by default to move to the next (/buffer +1) and previous (/buffer -1) buffers.
However, personally I prefer to have these simple keyboard shortcuts bound to jumping between words, (even though most editors use ctrl+cursor keys for this). I might someday switch my alt and ctrl behaviour around, but I kinda have got used to this behaviour...
Complete word with mouse gesture to the right in input bar
/key bindctxt mouse @bar(input):button1-gesture-right /input complete_next will trigger completion (similar to pressing tab) if you click-drag with your mouse to the right in the input bar. This might not sound very useful at first, but I find it rather useful while using WeeChat from my mobile phone which lacks a tab key on the on-screen keyboard.
Suggested / My aliases
WeeChat comes with an excellent Alias module, which allows for you to add your own client-side commands. You can use this for shortening existing commands (/close instead of /buffer close for instance), to combine various commands into a single command, or to alias often used replies.
Prefixed opnotice/wallchops
Since not everyone recognises ops-only channel notices (/opnotice or /wallchops $*) for what they are (possibly because some clients show them as regular (channel) notices), I've added this little alias myself:
This will insert /opnotice [ops-only notice] whatever was typed after the /onotice command on the input bar. You could leave out the /input insert part as well so it sends directly, but I like to review the command before hitting enter again.
Alternatively, if you also want to include the channel name, you could also use the following alias:
/alias onotice /opnotice [@$channel] $1-
This will make the wallchops show up as [@#weechat] Hello world! instead.
/alot
Because I love Alots a lot, I've added this little alias that inserts the url of the pages describing what an alot is, onto the input bar:
These kinds of aliases are useful if you frequently need a certain page of which you can't remember the URL.
Buffer Move
Before buffers.pl got mouse support which allows you to click and drag buffers around to where you want them, I used the following alias to move buffer $1 to position $2:
/alias bmove /buffer $1; /buffer move $2
But I would suggest you just use buffers.pl or in more recent versions of weechat the built-in buflist plugin and enable mouse support instead, so you can click-and-drag the buffers in the right order.
Useful if you filter the list of nicks (from /names for instance) by default, but do want to show them when you manually do a names lookup. It will disable the filter for 3 seconds and then automatically re-enable them:
As you can see, this alias links several commands together by splitting them with the ; (semi-colon) character.
/konamicode
/alias konamicode /input insert ↑ ↑ ↓ ↓ ← → ← → B A ((select) start)
cheatmode enabled!
/irc-analogy
/alias irc-analogy /input insert an IRC server is like a shopping mall. It provides space for various shops. While the mall owner (read: the server's staff) might control some of the shops (read: channels), most of them are 'owned' (registered) by individual parties (channel founders). Each of the shops (channels) usually have their own subject/topic of conversation and their own rules and guidelines. All of the shops (channels) can be reached via the main entrance (any IRC client connected to the server's address), but some of them might have their own entrance (an IRC applet/client on their own website). So, the fact that you have connected through website X about subject Y, doesn't mean all other channels belong to the same website / share the same topic of conversation.
... because I got tired of manually explaining that most channels on Esper.net aren't about minecraft...
WeeChat currently still doesn't have an official way to install or export themes, but FlashCode did write an alpha script, theme.py for it a while ago, as well as a WeeChat Themes page.
Judging by this reddit question, the script is still confusing to people though, so I'll write some details about it.
If you put this (alpha) script in ~/.weechat/python/ (or wherever your weechat userdir resides), and load it with /script load theme.py then you can get the help text with: /help theme:
[python/theme] /theme list []
info|show []
install
installfile
undo
save
backup
restore
export [-white]
WeeChat theme manager
list: list themes (search text if given)
info: show info about theme (without argument: for current theme)
show: show all options in theme (without argument: for current theme)
install: install a theme from repository
installfile: load theme from a file
undo: undo last theme install
save: save current theme in a file
backup: backup current theme (by default in ~/.weechat/themes/_backup.theme); this is done the first time script is loaded
restore: restore theme backuped by script
export: save current theme as HTML in a file (with "-white": use white background in HTML)
Examples:
/theme save /tmp/flashcode.theme => save current theme
It is worth noting that /theme save, /theme installfile and /theme export require an expanded path, so you can't use ~ to indicate your homedir.
To save your theme, you can use: /theme save /home/fixato/.weechat/themes/fixato-20130428.theme
This should return: Theme saved to "/home/fixato/.weechat/themes/fixato-20130428.theme"
To load your theme, you can use: /theme load /home/fixato/.weechat/themes/fixato-20130428.theme
This should return: Theme saved to "/home/fixato/.weechat/themes/_undo.theme" Theme "/home/fixato/.weechat/themes/fixato-20130428.theme" installed (103 options set)
You can also export how the theme would look, to an HTML file with: /theme export /home/fixato/fixato.org/guides/weechat/fixato-20130428.html
Which should return: Theme exported as HTML to "/home/fixato/fixato.org/guides/weechat/fixato-20130428.html"
The resulting HTML file is available at: http://fixato.org/guides/weechat/fixato-20130428.html.
What follows are some script snippets from my scripts that you could use while coding your own scripts
Retrieve target msgbuffer:
Want to follow the user-defined target msgbuffer settings, then use the following Python function to retrieve the appropriate buffer pointer based on the server and nickname:
def find_buffer(server, nick, message_type='whois'):
# See if there is a target msgbuffer set for this server
msgbuffer = weechat.config_string(weechat.config_get('irc.msgbuffer.%s.%s' % (server, message_type)))
# No whois msgbuffer for this server; use the global setting
if msgbuffer == '':
msgbuffer = weechat.config_string(weechat.config_get('irc.msgbuffer.%s' % message_type))
# Use the fallback msgbuffer setting if private buffer doesn't exist
if msgbuffer == 'private':
buffer = weechat.buffer_search('irc', '%s.%s' %(server, nick))
if buffer != '':
return buffer
else:
msgbuffer = weechat.config_string(weechat.config_get('irc.look.msgbuffer_fallback'))
# Find the appropriate buffer
if msgbuffer == "current":
return weechat.current_buffer()
elif msgbuffer == "weechat":
return weechat.buffer_search_main()
else:
return weechat.buffer_search('irc', 'server.%s' % server)
Set default settings:
The following snippet can be used to set some default settings for your Python script:
my_settings = (
("your_settingname", "default value for your_settingname", "Description for your_settingname."),
("sort_order", "users", "Last used sort order for the channel list."),
)
version = weechat.info_get("version_number", "") or 0
for option, default_value, description in my_settings:
if not weechat.config_is_set_plugin(option):
weechat.config_set_plugin(option, default_value)
if int(version) >= 0x00030500:
weechat.config_set_desc_plugin(option, description)
YourBNC Configuration
YourBNC is one of several free IRC Bouncer providers out there. After receiving some questions on Esper.net about how to set up WeeChat for it, I decided to add this small section to my guide, in the hopes some will find it useful.
Should there be any errors, feel free to find me on the Esper network, or in #WeeChat on freenode.
Legend to the examples format
In the following command examples, you will see certain $variables. You will need to replace these with some variable such as a username or password given by YourBNC, or for instance in the case of $WeeChatServerName, with a value you've picked yourself. If you hover over these variables, you should get a title-tooltip with an example value.
Adding a server config for YourBNC
There are two ways to add a new server to WeeChat. A temporary one (/connect), and a permanent one (/server add). A temporary server will be deleted once you exit WeeChat, while the permanent one will still be there after you restart your WeeChat client.
It is possible to turn a temporary server into a permanent one with the /server keep $WeeChatServerName command though.
The $WeeChatServerName variable determines by what name the server is known within WeeChat. All settings for this server will be stored within the irc.server.$WeeChatServerName.* namespace. This does not have to equal the server address, and can also be just a single word, such as 'YourBNC'.
For instance, if you fill in YourBNC in place of $WeeChatServerName, all the server's WeeChat settings will be stored within the irc.server.YourBNC.* namespace.
The -nossl_verify argument is used to accept the StartCom SSL certificates of YourBNC, as it would otherwise be rejected due to hostname of the certificate (www.yourbnc.co.uk), not matching the hostname of the server, as well as the certificate and certificate issuer (StartCom) generally not being trusted/known by the IRC client.
SSL Fingerprint verification
If you want some extra assurance that the SSL certificate matches the one issued to YourBNC, you could ask YourBNC for the current certificate's fingerprint.
At the time of writing, this would be f2496dfd2562c749e70d871849f72eabe56ea90f. You can then tell WeeChat to always verify the SSL's fingerprint against this one.
If you've already added the server, you can use:
If the SSL certificate's fingerprint has changed, then WeeChat should now refuse to connect to the server. Remember that while it could indicate that someone is attempting a MitM-attack, it could also just be that YourBNC has renewed their certificate.
If you haven't added the server yet, just add the -ssl_fingerprint=f2496dfd2562c749e70d871849f72eabe56ea90f argument to the aforementioned /connect or /server add commands:
You can also add various channels to your auto-join by adding the -autojoin=#chan1,#chan2,#chanN argument to the aforementioned /connect or /server add commands:
Though I would suggest to just join the channels you want to auto-join and then use the autojoin.py script to add all your joined channels to autojoin setting for each server: /autojoin --run.
If you have a recent enough version of WeeChat, you can install this script with: /script install autojoin.py
Or just let the bnc keep you connected to the channels you join; though personally I like to keep a local backup of my auto-join channels too.
Remember to /save
As with any settings you change, do remember to call the /save command to write the setting changes to the config file on disk, so they will persist after you exit WeeChat.
Further Reading
If you want to learn more about the /server command, please check out the Managing Servers in WeeChat section, where I go into some more details about managing your IRC server connections within WeeChat.
If you want to know more about scripts, do check out the Scripts-section.
Weechat has a handy feature for quite some time now: Triggers. It allow you to trigger actions based on signals, along with replacing texts.
Display active buffer's server buffer in separate window
crypt0kraken on #weechat wanted to know how to display the server buffer for the currently active buffer:
[2021-05-26 18:37:15 CEST] [crypt0kraken / ircs://irc.libera.chat/#weechat] how can I create a window that always shows the server buffer of the corresponding network/channels I'm viewing in another window?
After a lot of fiddling I ended up with the following /trigger solution:
/eval /set plugins.var.trigger.switch_active_server_buffer.target_window "${window.number}"
/trigger add switch_active_server_buffer signal "window_switch;buffer_switch" "${window.number} != ${plugins.var.trigger.switch_active_server_buffer.target_window} && ${server} !=" "" "/eval /set plugins.var.trigger.switch_active_server_buffer.previous_window ${window.number}; /eval /set plugins.var.trigger.switch_active_server_buffer.server_buffer ${server}; /window ${plugins.var.trigger.switch_active_server_buffer.target_window}; /buffer ${plugins.var.trigger.switch_active_server_buffer.server_buffer}; /window ${plugins.var.trigger.switch_active_server_buffer.previous_window}"
The first command stores the number of the current window in plugins.var.trigger.switch_active_server_buffer.target_window, which will be the number of the target window where you want the server buffer displayed. So be sure to run this command in the same window as where you want the current server buffer displayed.
The second command is the actual trigger.
This trigger listens to window_switch and buffer_switch signals, and only triggers if the current window number isn't the target window number, and when the ${server} variable is not empty (in case of the core buffer for instance, or plugin buffers).
The command it triggers creates sets a couple of (intermediate) variables, before running a chain of commands that:
Switch to the target window, as defined in plugins.var.trigger.switch_active_server_buffer.target_window
Changes the buffer of the target window (which is now temporarily active) to the buffer name ${server} temporarily stored in plugins.var.trigger.switch_active_server_buffer.server_buffer.
(I'm storing ${server} in a temporary variable because it no longer would be accurate when the trigger switched windows.)
Switch back to the previous window, which was ${window.number} when the trigger executed, and temporarily stored in plugins.var.trigger.switch_active_server_buffer.previous_window for the same reasons as the previous command.
