WeeChat quick start guide

A recommended (but not mandatory) X terminal emulator for running WeeChat is rxvt-unicode. It has good UTF-8 support and works well with WeeChat’s default key bindings.

Run from your shell:

WeeChat has help for all commands, just issue:

To get help on a specific command, issue:

Help is available for options as well:

(where config is configuration name (weechat for core, or a plugin name), section the section of this configuration and option the option name).

To set options, issue:

WeeChat immediately uses the new value (you never need to restart WeeChat after changes to configuration).

All settings are saved when WeeChat ends (or with the /save command to force a write of the options).

The plugin fset allows you to easily browse options and change them.

For example to display WeeChat options:

IRC options:

The /fset command has completion on part of option names, so for example if you type /fset hot and press Tab this is completed as /fset hotlist. If you press Enter, options about the hotlist are displayed.

For more information about the /fset command and keys, see /help fset.

WeeChat "core" is only used to display data on screen and interact with the user, that means weechat core without plugins is useless (faithful users: IRC was part of core for versions ≤ 0.2.6).

All network protocols like IRC are provided in separate plugins.

Use the /plugin command to list loaded plugins, you should see "irc" and other plugins in the list.

You can add an IRC server with the /server command, for example:

In this command, freenode is the internal server name used by WeeChat: you’ll be able to connect with /connect freenode and the server options are irc.server.freenode.xxx.

As usual, help is available if you’re lost:

WeeChat uses default values for all servers ("fall backs"), if you don’t specify a specific value for a server option. These default options are "irc.server_default.*".

For each server option, WeeChat uses its value if it is defined (not "null"). Otherwise WeeChat uses default value ("irc.server_default.xxx").

For example there are default nicks (based on your un*x login), and you can override them for the freenode server with following command:

To set the user and real names:

To enable auto-connect to server at startup:

To connect with SSL:

If SASL is available on the server, you can use it for authentication (you will be identified before you join channels):

To run a command after connection to server, for example to authenticate with nickserv (only if you don’t use SASL for authentication):

If you want to protect your password in configuration files, you can use secured data.

First setup a passphrase:

Then add a secured data with your freenode password:

Then you can use ${sec.data.freenode_password} instead of your password in the IRC options mentioned above, for example:

To auto-join some channels when connecting to server:

To remove a value of a server option, and use the default value instead, for example to use default nicks (irc.server_default.nicks):

Other options: you can setup other options with the following command ("xxx" is option name):

With this command, WeeChat connects to the freenode server and auto-joins the channels configured in the "autojoin" server option.

By default, server buffers are merged with WeeChat core buffer. To switch between the core buffer and server buffers, you can use Ctrl+x.

It is possible to disable auto merge of server buffers to have independent server buffers:

Join a channel:

Part a channel (keeping the buffer open):

Close a server, channel or private buffer (/close is an alias for /buffer close):

Disconnect from server, on the server buffer:

Open a buffer and send a message to another user (nick foo):

Close the private buffer:

A buffer is a component linked to a plugin with a number, a category, and a name. A buffer contains the data displayed on the screen.

A window is a view on a buffer. By default there’s only one window displaying one buffer. If you split the screen, you will see many windows with many buffers at same time.

Commands to manage buffers and windows:

For example, to vertically split your screen into a small window (1/3 width), and a large window (2/3), use command:

To remove the split:

WeeChat uses many keys by default. All these keys are in the documentation, but you should know at least some vital keys:

According to your keyboard and/or your needs, you can rebind any key to a command with the /key command. A useful key is Alt+k to find key codes.

For example, to bind Alt+! to the command /buffer close:

You’ll have a command line like:

To remove key:

On some distros like Debian, plugins are available via a separate package (like weechat-plugins). Plugins are automatically loaded when found (please look at the WeeChat documentation to load/unload plugins or scripts).

Many external scripts (from contributors) are available for WeeChat, you can download and install scripts from the repository with the /script command, for example:

See /help script for more info.

A list of scripts is available in WeeChat with /script or at this URL: https://weechat.org/scripts

You can now use WeeChat and read FAQ/documentation for any other questions: https://weechat.org/doc

Enjoy using WeeChat!