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:
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:
Let's first check the TERM environment variable, to make sure it is the right one for displaying the 256 colours that WeeChat supports:
Ideally this should say something like xterm-256color (as mine returns), rxvt-unicode-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.
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:
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:
As you can see in the terminal example output displayed above it displays a bunch of LC_ and LANG variables that are set to en_GB.UTF-8:
LANG=en_GB.UTF-8 LANGUAGE=en_GB.UTF-8 LC_CTYPE="en_GB.UTF-8" LC_NUMERIC="en_GB.UTF-8" LC_TIME="en_GB.UTF-8" LC_COLLATE="en_GB.UTF-8" LC_MONETARY="en_GB.UTF-8" LC_MESSAGES="en_GB.UTF-8" LC_PAPER="en_GB.UTF-8" LC_NAME="en_GB.UTF-8" LC_ADDRESS="en_GB.UTF-8" LC_TELEPHONE="en_GB.UTF-8" LC_MEASUREMENT="en_GB.UTF-8" LC_IDENTIFICATION="en_GB.UTF-8" LC_ALL=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-curses` | 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. ;-)
With all of this set up properly, you shouldn't have any problems with seeing wrong characters, or not being able to use or see accented characters. If you do, I suggest you have a read at the WeeChat F.A.Q.: I don’t see some chars with accents, what can I do?
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:
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:
SESSIONNAME='weechat-tutorial' && (tmux attach-session -t $SESSIONNAME || tmux new-session -s $SESSIONNAME)
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:
If this shows screen-256color then you are all set!
Which brings us to the next section, starting and setting up WeeChat!
Yes, I spent quite some time on making you check your terminal first, but. We are ready to start running WeeChat now!
Okay, I lied. :P Before we start WeeChat, let's just check first if it displays the 256 colours correctly:
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?.
Right, let's start WeeChat. The application is called weechat-curses, probably because it allows for non-curses frontends to the weechat core to be created as well.
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:
There it is, WeeChat, in its glorious appearance! Glorious? Well… perhaps not yet, but it will be once we are done with it!
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. ;-)
It also tells us that several bars have been created.
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.
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.
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
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.
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
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.
Remember that nicklist I mentioned? Let's have a closer look at the options this bar has.
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:
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.
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.
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.
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 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.
I suggest to also have a look at the output of:
which gives you the same list, but now with short descriptions for each of the commands.
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:
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!
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.
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.
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.).
Of course the completion behaviour is also configurable in WeeChat. For instance:
See weechat.completion.* settings for an overview of all the WeeChat completion options available.
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 list. It can also be used to insert nicks from your nicklist, or even open query windows from the nicklist.
Sound great huh? So how to enable this feature? It's easy:
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 enabled for mouse (normal)
Clicking somewhere in the screen will now for instance show:
Mouse: button1-event-down, (89,40) -> (89,40) Mouse: button1-gesture-up, (89,40) -> (89,29)
Or when clicking on a buffer name in buffers.pl:
Mouse: button1-event-down, (6,1) -> (6,1) Mouse: button1, (6,1) -> (6,1) Command for key: "hsignal:buffers_mouse" Sending hsignal: "buffers_mouse"
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!
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.
You can create your own C plugins for WeeChat, but that goes beyond the scope of this guide. Instead, I would refer you to the Plugins in WeeChat section in the official documentation and the WeeChat Plugin API documentation.
There are several ways of managing the plethora of scripts that are available. This section will describe them briefly.
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:
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.
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:
The /script buffer's title bar shows quite a lot of information help texts such as shortcuts. Let's have a closer look:
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:
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.
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:
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.
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 info: Chat4All -- | - subject `C=NL,ST=Noord-Brabant,L=Den Bosch,O=Chat4All,OU=Chat4All IRC,CN=*.chat4all.org,EMAILemail@example.com', issuer `C=NL,ST=Noord-Brabant,L=Den Bosch,O=Chat4All,OU=Chat4All IRC,CN=chat4all.org,EMAILfirstname.lastname@example.org', 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
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.
Let's first find out where WeeChat is currently looking for the CA (certificate authorities) file, which defines which CAs are trusted:
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)
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:
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
If you try to connect to the network now, it should connect normally without errors:
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 trusted Chat4All -- | gnutls: receiving 1 certificate Chat4All -- | - certificate info: Chat4All -- | - subject `C=NL,ST=Noord-Brabant,L=Den Bosch,O=Chat4All,OU=Chat4All IRC,CN=*.chat4all.org,EMAILemail@example.com', issuer `C=NL,ST=Noord-Brabant,L=Den Bosch,O=Chat4All,OU=Chat4All IRC,CN=chat4all.org,EMAILfirstname.lastname@example.org', 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: connected to us.chat4all.org/6697 (126.96.36.199)
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.
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:
[server] (irc.conf) irc.server.freenode.addresses = "chat.freenode.net/6667" (default: (undefined)) irc.server.freenode.anti_flood_prio_high irc.server.freenode.anti_flood_prio_low irc.server.freenode.autoconnect irc.server.freenode.autojoin irc.server.freenode.autoreconnect irc.server.freenode.autoreconnect_delay irc.server.freenode.autorejoin irc.server.freenode.autorejoin_delay irc.server.freenode.away_check irc.server.freenode.away_check_max_nicks irc.server.freenode.capabilities irc.server.freenode.command irc.server.freenode.command_delay irc.server.freenode.connection_timeout irc.server.freenode.default_msg_part irc.server.freenode.default_msg_quit irc.server.freenode.ipv6 irc.server.freenode.local_hostname irc.server.freenode.nicks irc.server.freenode.notify irc.server.freenode.password irc.server.freenode.proxy irc.server.freenode.realname irc.server.freenode.sasl_mechanism irc.server.freenode.sasl_password irc.server.freenode.sasl_timeout irc.server.freenode.sasl_username irc.server.freenode.ssl irc.server.freenode.ssl_cert irc.server.freenode.ssl_dhkey_size irc.server.freenode.ssl_priorities irc.server.freenode.ssl_verify irc.server.freenode.username 34 options (matching with "*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
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.
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
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
This section will describe a couple of settings I personally quite like:
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
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.
/key bind Esck Alt+Backspace /input delete_previous_word
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
/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.
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.
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...
/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.
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.
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:
/alias onotice /input insert /opnotice [ops-only notice] $1-
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.
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:
/alias alot /input insert http://hyperboleandahalf.blogspot.com/2010/04/alot-is-better-than-you-at-everything.html
These kinds of aliases are useful if you frequently need a certain page of which you can't remember the URL.
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 and enable mouse support instead, so you can click-and-drag the buffers in the right order.
/alias recursion /input insert /recursion
Inspired by the various pun/sunglasses moments from CSI: Miami, I wrote this silly set of 3 aliases:
/alias pun1 /input insert ( ಠ_ಠ)
/alias pun2 /input insert ( ಠ_ಠ)>--■-■
/alias pun3 /input insert (-■_■) YEAAAAAAAAAAAAAAAAAAAAAHHHHHHHHHHHH
Now isn't that.... punderful? =)
another silly alias making it look like I am looking around the channel:
/alias lookaround /input insert /me looks around ('-' ) (._. ) (o_o) ( ._.) ( '-')
... see what I did there? ;-)
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:
/filter add nicks * irc_366 *
/filter enable nicks
/alias mynames /names;/filter toggle nicks; /wait 3s /filter toggle nicks
As you can see, this alias links several commands together by splitting them with the ; (semi-colon) character.
/alias konamicode /input insert ↑ ↑ ↓ ↓ ← → ← → B A ((select) start)
/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...
/alias irc-clients /input insert http://wiki.chat4all.org/index.php/IRC-Client
A list of IRC clients with screenshots that I have assembled along with some other Chat4All operators.
/alias Hacker_what_is_a /input insert /pt http://www.youtube.com/watch?v=hoDOrKZK3Kg
The /pt command is provided by the pagetitle.py script and will insert the URL's page title after the URL.
/alias gangnam /say ヽ(゜∇゜)ノ Eeeeyyyy sexy laaaaaadyyyy;/say ヘ(￣ー￣ヘ) Op (ノ￣ー￣)ノ Op (〜￣▽￣)〜 Op 〜(￣△￣〜) Op;/say (☞ﾟ∀ﾟ)☞ Oppan Gangnam Style;/say ヾ(⌐■_■)ノ♪
Gangnam IRC Style!
/alias dances /input insert ┌(・。・)┘ ♪ └(・。・)┐ ♪ ┌(・。・)┘ $1-
Get your feet off the ground!
/alias bro /input insert ლ(°◡°ლ)
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.
You can find a bunch of themes that users have created with it on http://weechat.org/themes/
What follows are some script snippets from my scripts that you could use while coding your own scripts
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)
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)
As you can see, this guide is still far from finished. I'll try to update it in the coming weeks.