Samir Parikh / Blog

Originally published on 03 May 2020



In some of my last posts, which were written in what feels like another time, I wrote about how I was starting to get back into IRC. In those posts, I wrote about how to install a web-based client to join networks and chat in various channels. Today, I'm going to document how I've been using a commandline client called WeeChat to access IRC networks and join various channels. The WeeChat website already has a lot of good documentation, including a Quick Start Guide, a detailed User's Guide and an FAQ. Think of this post, however, as a gentle introduction in how to get started with using WeeChat quickly. Once you start to get comfortable with some of the basics, you'll be much better prepared to navigate the documentation once you understand the basics of how WeeChat works.

Getting Started

To install WeeChat on Ubuntu 18.04, it's as simple as following the instructions on the WeeChat download page:

$ sudo apt-get install dirmngr gpg-agent apt-transport-https
$ sudo apt-key adv --keyserver hkps:// --recv-keys 11E9DE8848F2B65222AA75B8D1820DB22A11534E
Executing: /tmp/apt-key-gpghome.Z1XZyFxd8e/ --keyserver hkps:// --recv-keys 11E9DE8848F2B65222AA75B8D1820DB22A11534E
gpg: key D1820DB22A11534E: public key "WeeChat Debian Repository " imported
gpg: Total number processed: 1
gpg:               imported: 1
$ echo "deb bionic main" | sudo tee /etc/apt/sources.list.d/weechat.list
deb bionic main
$ echo "deb-src bionic main" | sudo tee -a /etc/apt/sources.list.d/weechat.list
deb-src bionic main
$ sudo apt-get update
$ sudo apt-get install weechat-curses weechat-plugins weechat-python weechat-perl

To run WeeChat, enter:

$ weechat

You should then be presented with an ncurses style application looking something like this:

1.weechat│WeeChat 2.8 (C) 2003-2020 -                                               
         │16:35:00 |   ___       __         ______________        _____ 
         │16:35:00 |   __ |     / /___________  ____/__  /_______ __  /_
         │16:35:00 |   __ | /| / /_  _ \  _ \  /    __  __ \  __ `/  __/
         │16:35:00 |   __ |/ |/ / /  __/  __/ /___  _  / / / /_/ // /_  
         │16:35:00 |   ____/|__/  \___/\___/\____/  /_/ /_/\__,_/ \__/  
         │16:35:00 | WeeChat 2.8 [compiled on Mar 29 2020 08:48:22]
         │16:35:00 | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
         │16:35:00 | 
         │16:35:00 | Welcome to WeeChat!
         │16:35:00 | 
         │16:35:00 | If you are discovering WeeChat, it is recommended to read at least the quickstart
         │         | guide, and the user's guide if you have some time; they explain main WeeChat
         │         | concepts.
         │16:35:00 | All WeeChat docs are available at:
         │16:35:00 | 
         │16:35:00 | Moreover, there is inline help with /help on all commands and options (use Tab key
         │         | to complete the name).
         │16:35:00 | The command /fset can help to customize WeeChat.
         │16:35:00 | 
         │16:35:00 | You can add and connect to an IRC server with /server and /connect commands (see
         │         | /help server).
         │16:35:00 | 
         │16:35:00 | ---
         │16:35:00 | 
         │16:35:00 | Bar "input" created
         │16:35:00 | Bar "title" created
         │16:35:00 | Bar "status" created
         │16:35:00 | Bar "nicklist" created
         │16:35:00 | New key binding (context "default"): meta2-1;5P => /bar scroll buflist * -100%
         │16:35:00 | New key binding (context "default"): meta2-1;5Q => /bar scroll buflist * +100%
         │16:35:00 | New key binding (context "default"): meta-meta-OQ => /bar scroll buflist * e
         │16:35:00 | New key binding (context "default"): meta2-1;3Q => /bar scroll buflist * e
         │16:35:00 | New key binding (context "default"): meta2-1;3P => /bar scroll buflist * b
         │16:35:00 | New key binding (context "default"): meta-meta-OP => /bar scroll buflist * b
         │16:35:00 | New key binding (context "default"): meta-OQ => /bar scroll buflist * +100%
         │16:35:00 | New key binding (context "default"): meta-OP => /bar scroll buflist * -100%
         │16:35:00 | New key binding (context "default"): meta-meta2-12~ => /bar scroll buflist * e
         │16:35:00 | New key binding (context "default"): meta-meta2-11~ => /bar scroll buflist * b
         │16:35:00 | New key binding (context "default"): meta2-12^ => /bar scroll buflist * +100%
         │16:35:00 | New key binding (context "default"): meta2-12~ => /bar scroll buflist * +100%
         │16:35:00 | New key binding (context "default"): meta2-11^ => /bar scroll buflist * -100%
         │16:35:00 | New key binding (context "default"): meta2-11~ => /bar scroll buflist * -100%
         │16:35:01 | Plugins loaded: alias, buflist, charset, exec, fifo, fset, irc, logger, perl,
         │         | python, relay, ruby, script, spell, trigger, xfer
         │[16:39] [1] [core] 1:weechat                                                                   
         │<enter commands here>

At this point, I'm going to walk through some of the common commands and configuration settings that I use. If you are new to WeeChat, I would suggest having the Quick Start Guide handy as it also serves as a good (and official) introduction to using WeeChat.

WeeChat uses "buffers" to display information such as the various IRC channels you're logged into. Think of these buffers as being comparable to "windows" in Irssi though WeeChat also has the concept of windows in addition to buffers. For now, let's assume buffers and windows are the same in WeeChat recognizing that this is not technically correct.

To add an IRC network that you'd like to connect to, use the /server add command, for example:

/server add freenode

To join a network using something other than a default port or one that uses SSL, run the following command:

/server add darkscience -ssl

This is important if you want to connect to a network using Simple Authentication and Security Layer, or SASL and to automate the connection and identification processes described in more detail below. For the Freenode network, add the server via:

/server add freenode -ssl
/set irc.server.freenode.sasl_mechanism PLAIN

To list all of the networks whose servers you've connected to, run:

/server list

To then connect to the network, use the /connect command:

/connect freenode
/connect darkscience

To remove a network from the list of servers you have connected to, use the /server del command:

/server del freenode

Once you've connected to a network, you can change your nick(name):

/nick newnick

To join a channel, use the /join command:

/join #weechat

This will open a new buffer for the IRC channel.

To leave a channel, you can use the standard IRC command

/part "goodbye message"

To close the buffer, execute

/buffer close



To log out of a network, use:

/msg nickserv logout

Setting Appearances

After joining a channel, you should see a buffer similar to the example below.

1.freenode   │ | Latest stable version: 2.8 | English support channel, ONLY abou>>
  weechat    │01:17:00 --> | jomamma (~weechat@ has joined #weechat      │@ChanServ
2.  #freenode│01:17:00  -- | Topic for #weechat is " | Latest     │@FlashCode
3.  #weechat │             | stable version: 2.8 | English support channel, ONLY      │@kolter
             │             | about WeeChat software | Please read docs before asking! │@nils_2
             │             | | Bug reports are welcome ONLY for latest stable or      │+weebot
             │             | devel | Off-topic chan: #weechat-offtopic | Fingerprint: │ _casey_
             │             | A9AB 5AB7 78FA 5C35 22FD 0378 F82F 4B16 DEC4 08F8"       │ _flow_
             │01:17:00  -- | Topic set by FlashCode ( on Sun,  │ _h4rd3n3D_
             │             | 29 Mar 2020 08:09:00                                     │ _Warl0ck
             │01:17:01  -- | Channel #weechat: 870 nicks (4 ops, 1 voice, 865         │ ablackack
             │             | normals)                                                 │ Ac-town
             │01:17:01  -- | PvNotice(ChanServ): Welcome to WeeChat english support   │ aclaivi
             │             | channel. IMPORTANT: you *MUST* have read docs and FAQ    │ Acou_Bass
             │             | before asking something on this channel! Read them at:   │ acro
             │             |                                 │ ada
             │01:17:01  -- | URL for #weechat:                   │ ada_
             │01:17:02  -- | Channel created on Sun, 26 Nov 2006 06:42:51             │ adsr
             │                                                                        │ aedend
             │                                                                        │ aeiro
             │                                                                        │ afk
             │                                                                        │ Armageddon    ++
             │[01:17] [3] [irc/freenode] 3:#weechat(+Ccntj 6:10){870} [H: 2(1,2)]                       

WeeChat is almost infinitely customizable. In this post, I'm just going to scratch the surface of some of the things you can do. I would recommend consulting the excellent documentation to explore more options to tweak the client to your tastes.

The bar to the left is called the "buflist", displaying a list of all current buffers. The bar to the right is called the "nicklist" which displays a list of all the nicks in the current channel. You can hide one or both of them using the /bar hide command as in:

/bar hide nicklist
/bar hide buflist

You can reveal them again using /bar show:

/bar show nicklist
/bar show buflist

If the nicklist is hidden but you want to quickly see who's logged into an IRC channel, run the command /names. If you want to quickly see a list of open buffers when the buflist is hidden, navigate to buffer 1 and run /buffer list. (See below for how to move between buffers.)

Another way to quickly show or hide the bars is using the /bar toggle command:

/bar toggle nicklist

Run the /bar toggle command again to undo what you just did.

To adjust the number of characters that are displayed for each nick in the chat area, run the following command:

/set weechat.look.prefix_align_max 15

Note that the default width is 15 so use a lower number to reduce the width.

To globally filter all join, part and quit updates, run

/filter add joinquit * irc_join,irc_part,irc_quit *

To scroll up or down in an IRC's chat history, use <PgUp> and <PgDn>.

To scroll up one page in the nicklist, use /bar scroll nicklist * -100%. Similarly, to scroll down one page in the nicklist, use /bar scroll nicklist * +100%.

To navigate between buffers, you have a few choices. To cycle through the open buffers sequentially, use <Ctrl>-N and <Ctrl>-P. You can also go directly to a buffer by entering `buffer n where n is the number of the buffer in the buflist. You can also go directly to a buffer using it's name via /buffer name, for example /buffer weechat.

If you have logged into multiple IRC networks, you'll see them listed under buffer 1 in the buflist. To navigate between the networks, first go to buffer 1 and then press <Ctrl>-X to cycle through the various networks you've connected to.

Basic Automation

To have WeeChat automatically join your preferred networks (assuming you have already added the server via the /server add command), run:

/set irc.server.networkname.autoconnect on

for each network. For example, in buffer 1, run:

/set irc.server.freenode.autoconnect on
/set irc.server.geekshed.autoconnect on
/ser irc.server.snoonet.autoconnect on

Again, for the above commands to work you need to ensure that you have already added the network using the /server add command.

To see which networks you have configured WeeChat to automatically join upon starting, run:

/fset irc.server.*.autoconnect

This opens another buffer and shows you how the irc.server.*.autoconnect option is configured and highlights which networks you have changed the default settings for.

If you want WeeChat to automatically connect you to a network using a default nick which was registered with a password, you'll need to securely store that password for later use.

First, create a passphrase which will be used to encrypt data such as passwords in a file called sec.conf:

/secure passphrase superSecretPassphrase

Second, set your nick's network password:

/secure set networkname_nickname_password password

How you proceed next is determined by whether you connect to the network via SASL or not.

Automatically Connecting to and Identifying with Network via SASL

First, specify the nick you want to use on the network:

/set irc.server.networkname.sasl_username nickname

Then, provide the password you saved above which was used to register the nick:

/set irc.server.networkname.sasl_password "${}"

For additional information, please see this page.

Set your default nick for a network:

/set irc.server.networkname.nicks "nickname"

For example,

/set irc.server.freenode.nicks "johnDoe"

As above, to see which nicks you have configured to join as default in your networks, run

/fset irc.server.*.nicks

The next time you launch WeeChat, you should be logged into that network with your desired nick.

Automatically Connecting to a Network without SASL

Set your default nick as described in the section above:

/set irc.server.networkname.nicks "nickname"

Then run the command to identify your nick with the required password

/set irc.server.networkname.command "/msg nickserv identify ${}"

Automatically Join Channels

To automatically join channels (after you have connected to a network), use the following command:

/set irc.server.networkname.autojoin "#channel1,#channel2"

For example:

/set irc.server.freenode.autojoin "#weechat,#ubuntu"

Please consult the documention for more details and options on automating WeeChat.

Learning More

As I mentioned earlier, the WeeChat website has a lot of great documentation. If you ever get stuck on how to use a command, you can always run the /help command in buffer 1 for more information. I would also highly recommend hanging out in #weechat on Freenode and asking any questions there, assuming you have already gone through the documentation. The people I've encountered there are quite friendly.