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 myself¹, but it gets the job done.

table of contents

• installation
• launching
• server configuration
  • add servers
• account setup
  • authentication model
• client config
  • automatic authentication
  • hide joined/quit notifications
  • autojoin channels
  • hide user nick modes
• usage guide
• depends on
• source code

installation

$ sudo apt install weechat

launching

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.

server configuration

To use IRC you pick a server. The most popular is https://libera.chat but there’s also https://oftc.net.

You can even host your own; the protocol is all standardized and open source implementations exist such as https://github.com/inspircd/inspircd. See the IRC RFC bullet at https://weechat.org/files/doc/weechat/stable/weechat_user.en.html#features.

add servers

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.

account setup

The following is one-time account setup, so if you already have IRC accounts on the servers you’re connecting to, you can skip this.

authentication model

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 username (“nick”, short for nickname) like so:

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

or one-off:

/nick <yourusername>

registration

Once you’ve chosen your nick, register it with the special user NickServ:

/msg NickServ register <your_new_libera_password> <email>

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

The NickServ will respond with instructions:

NickServ (NickServ@services.libera.chat): An email containing nickname
NickServ (NickServ@services.libera.chat): Please check the address if you
NickServ (NickServ@services.libera.chat): If you do not complete registration
within one day, your nickname will expire.

At least for Libera, you’ll get the option to message NickServ a verification:

/msg NickServ VERIFY REGISTER <nick> <verification_code>

or go to a verification link. If you look at the URL you’ll see it’s the same code either way.

logging on

Registering an account logs you in. If you /exit weechat client and reopen it, or just open weechat again later, 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 if you’re using Linux.

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

This highlights one of the quirkiest aspects of IRC. You can pretend to be just about anybody … for 30 seconds. Eventually it will reset your nick to something like Guest5791, but you could have already sent some messages as your spoofed name.

Thus I recommend not sharing sensitive information over IRC, rather to use other trustworthy communication channels such as in person, authenticated video chat, or encrypted message (Signal).

If you’re using IRC as I do, to chat about software, nicks don’t really matter. You can tell who knows what they’re talking about by their message content. In fact if you want you could stick to a random guest name; as long as you don’t spam, most channels would probably hear you out.

client configuration

automatic authentication

It’s a hassle to 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 a password:

/secure set libera_password <libera_password>

And use it like so:

/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 drowning 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.

usage guide

That’s all a lot of config, now on to usage. Fortunately it’s pretty simple.

Join a channel with /join #channelname, like so:

/join #python

Now you’ll see the channel list below the server, and when you type a message and hit enter it’ll send it to the channel.

You mention users by simply putting their name in a message. If you start to type a name, you can tab complete it, which will add the username and a colon. So it’s customary to mention users like so:

someuser: thanks for your help

Leave a channel with /close.

See the list of channels on a server with /list.

You can move between buffers like individual channels and the server buffer with alt-up and alt-down.

Keep an eye on the server buffer; messages like “no such channel” upon joining a nonexistent channel will go there, rather than displaying in the buffer other channels.

One last feature you might not expect IRC to have at all: direct messages. Just like you /msg NickServ, you can /msg any user, and your conversation with them will show in its own buffer, with their name.

Often you’ll carry on a conversation with another user in a channel where what you’re talking about is on topic, but direct messages work pretty darn well. Still, I wouldn’t send anything private over even direct message.

Close weechat with /exit.

This is just a small start to a usage guide; while I’m working on this guide you can read the extremely comprehensive user guide at https://weechat.org/files/doc/weechat/stable/weechat_user.en.html.

depends on

• c
• c++
• cmake

source code

https://github.com/weechat/weechat