Razzi's guide to weechat


The command line irc client I’m using these days is weechat. It’s not exactly the irc client I’d make myself1, but it gets the job done.


$ sudo apt install weechat


Launch it at the command line with weechat. It’ll open its text user interface full screen.

From there you are presented with the “weechat” buffer.

Your cursor will be at the command line at the bottom of the screen.

You can enter slash commands from there, such as /help.

Scroll the output buffer using PgUp and PgDn.

Connect to a server

Irc allows you to connect to multiple servers. You can even host your own.

Add a server like so:

[...] /server add libera irc.libera.chat/6697 -ssl -autoconnect

Handily, this example can be found verbatim in /help server.

The server will autoconnect the next time you launch weechat. To connect in the current session, enter:

[...] /connect libera

The server will open in a new buffer for libera. You can see your buffers on the left an area called the buflist.

You can move between buffers with meta+up and meta+down.


The irc auth model is a bit funky - you authenticate to a server by messaging a special user called NickServ.

By default, your irc username will be the same as your computer username. If you don’t want to use that, persistently customize your “nick” like so:

[...] /set irc.server.libera.nicks <yourusername>

or one-off:

[...] /nick <yourusername>


Register your nickname with the special user NickServ:

[...] /msg NickServ register <libera_password> <email>

The password will show as *********. I guess it can’t have spaces.

The NickServ will respond with instructions.

Logging on

When you log on, you’ll see a set of messages like:

| NickServ (NickServ@services.libera.chat): This nickname
| is registered. Please choose a different nickname, or
| identify via /msg NickServ IDENTIFY yourusername <password>
| NickServ (NickServ@services.libera.chat): You have 30
| seconds to identify to your nickname before it is
| changed.

Like it says, you can authenticate by messaging the special NickServ user, as follows:

/msg NickServ identify <your password>

You might want to paste in a password using control+shift+v.

Your password will display as ********.

Automatic authentication

It’s a hassle to do message your password every time you connect to irc, so it’s nice to set your password persistently.

Set your username like so:

[...] /set irc.server.libera.sasl_username <nickname>

For your password to be encrypted on disk, you’ll need to set a weechat password as follows:

[...] /secure passphrase <weechat_password>

Now you can set and use passwords like so:

[...] /secure set libera_password <libera_password>
[...] /set irc.server.libera.sasl_password "${sec.data.libera_password}"

When you open weechat, it’ll prompt you for your weechat passphrase, but you can configure it to read the password from your command-line password manager such as pass:

/set sec.crypt.passphrase_command "pass weechat"

Read more about secure storage features with /help secure.

Hide joined/quit notifications

In a channel like #debian with hundreds of users, clients will come and go frequently, often drowining out the actual conversation. To hide these use:

[...] /filter add irc_smart * irc_smart_filter *

This “smart filter” means people who spoke recently will still have their exits and entrances posted. Read about this more with /help filter.

Autojoin channels

If you’d like to automatically join all the channels you had open when you last used weechat, use:

/set irc.server_default.autojoin_dynamic on

Hide user nick modes

By your prompt you’ll see certain letters like Ziw. These are called user modes and you can read about them here: https://en.wikipedia.org/wiki/Internet_Relay_Chat#Standard_(RFC_1459)_modes. If you’re like me and you trust the servers to set the appropriate modes for you, you can turn off their display:

/set irc.look.item_nick_modes off

If you do this you can always view your mode manually with /mode.

Depends on

Source code



  1. My kind of irc client would be more command-line oriented: I’d expect to be able to join straight into a channel by something like irc libera #emacs, and also handle those trendy links like ircs://irc.libera.chat/lobsters. I’d also build a bouncer daemon into the irc client itself. If this irc client exists already let me know!