1. Start WeeChat

A recommended terminal emulator for X (but not mandatory) is rxvt-unicode (it has good UTF-8 support, and no problem with default keyboard bindings).

Run from your shell:

$ weechat

2. Online help / options

WeeChat has help for all commands, just issue:

/help

To get help on a specific command, issue:

/help command

To set options, issue:

/set config.section.option value

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

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

You can use /set option with partial name and wildcard "*" at the beginning or end to display all options containing letters. For example:

  • display all options (WeeChat and plugins): 

/set

  • display WeeChat options: 

/set weechat.*

  • display IRC plugin options: 

/set irc.*

You can display help for an option with /help, for example:

/help weechat.look.highlight

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

You can edit configuration files (*.conf) by hand and reload them by /reload command if you don’t want to use /set command.

3. Core vs plugins

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.

4. Add an IRC server

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

/server add freenode chat.freenode.net

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

/help server

5. Set custom IRC server options

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’s default nicks (based on your un*x login), and you can override them for freenode server with following command:

/set irc.server.freenode.nicks "mynick,mynick2,mynick3,mynick4,mynick5"

To set username and realname:

/set irc.server.freenode.username "My user name"
/set irc.server.freenode.realname "My real name"

To enable auto-connect to server at startup:

/set irc.server.freenode.autoconnect on

To connect with SSL:

/set irc.server.freenode.addresses "chat.freenode.net/7000"
/set irc.server.freenode.ssl on

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

/set irc.server.freenode.sasl_username "mynick"
/set irc.server.freenode.sasl_password "xxxxxxx"

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

/set irc.server.freenode.command "/msg nickserv identify xxxxxxx"
Note
 Many commands in option command can be separated by ; (semi-colon).

To auto-join some channels when connecting to server:

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

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

/set irc.server.freenode.nicks null

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

/set irc.server.freenode.xxx value

6. Connect to IRC server and auto-join channels

/connect freenode
Note
 This command can be used to create and connect to a new server without using /server command (should I repeat you can see help for this command with /help connect ?).

By default, server buffers are merged with WeeChat core buffer. To switch between 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:

/set irc.look.server_buffer independent

7. Join/part IRC channels

Join a channel:

/join #channel

Part a channel (keeping buffer open):

/part [quit message]

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

/close

8. IRC private messages

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

/query foo this is a message

Close the private buffer:

/close

9. Buffer/window management

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 screen, you will see many windows with many buffers at same time.

Commands to manage buffers and windows:

/buffer
/window

(I’ll not repeat here that you can get help with /help on these commands)

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

/window splitv 33

10. Key bindings

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

  • alt+←/→ or F5/F6: switch to previous/next buffer

  • F7/F8: switch to previous/next window (when screen is split)

  • F9/F10: scroll title bar

  • F11/F12: scroll nicklist

  • Tab: complete text in input bar, like in your shell

  • PgUp/PgDn: scroll text in current buffer

  • alt+a: jump to buffer with activity (in hotlist)

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

For example, to bind alt+y to command /buffer close:

/key bind (press alt-k) (press alt-y) /buffer close

You’ll have a command line like:

/key bind meta-y /buffer close

To remove key:

/key unbind meta-y

11. Plugins/scripts

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:

/script install iset.pl

See /help script for more info.

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

12. More documentation

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

Enjoy using WeeChat!