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).
All settings are saved when WeeChat ends (or with /save
command to force
a write of the options).
It is not recommended to edit configuration files by hand because WeeChat
may write them at any time (for example on /quit ) and after any change
you must run the command /reload (with the risk of losing other changes
that were not yet saved with /save ).You can use the command /set , which checks the value and applies immediately
the changes.
|
Help is available for options:
/help config.section.option
The plugin fset allows you to easily browse options and change them.
For example to display WeeChat options:
/fset weechat.*
IRC options:
/fset irc.*
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 /fset
command and keys, see /help fset
.
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
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:
/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 are 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 the user and real names:
/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"
Many commands in option command can be separated by ; (semi-colon).
|
If you want to protect your password in configuration files, you can use secured data.
First setup a passphrase:
/secure passphrase this is my secret passphrase
Then add a secured data with your freenode password:
/secure set freenode_password xxxxxxx
Then you can use ${sec.data.freenode_password}
instead of your password in
IRC options mentioned above, for example:
/set irc.server.freenode.sasl_password "${sec.data.freenode_password}"
To auto-join some channels when connecting to server:
/set irc.server.freenode.autojoin "#channel1,#channel2"
You can complete name and value of options with the Tab key and Shift+Tab for a partial completion (useful for long words like the name of option). |
To remove a value of a server option, and use the default value instead, for example to use default nicks (irc.server_default.nicks):
/unset irc.server.freenode.nicks
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
This command can be used to create and connect to a new server without using
/server command (see /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 a server, channel or private buffer (/close
is an alias for
/buffer close
):
/close
Closing the server buffer will close all channel/private buffers. |
Disconnect from server, on the server buffer:
/disconnect
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
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
To remove the split:
/window merge
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+← / Alt+→ or F5 / F6: switch to previous/next buffer
-
F1 / F2: scroll bar with list of buffers ("buflist")
-
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+! to command /buffer close
:
/key bind (press alt-k) (press alt-!) /buffer close
You’ll have a command line like:
/key bind meta-! /buffer close
To remove key:
/key unbind meta-!
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 go.py
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!