WeeChat is a highly extendable and feature rich IRC Client currently under heavy development.
- 1 Installing
- 2 Running WeeChat
- 3 Configuration
- 4 Connecting to a server
- 5 Creating a Server profile
- 6 Configuring SSL
- 7 Tips and Tricks
- 8 Troubleshooting
- 9 Getting Help
- 10 See also
Install the package, or AUR for the development version.
WeeChat is going to have multiple interfaces at some point, run weechat-[interface] to start WeeChat.
As WeeChat currently only has an Ncurses interface. The command to start WeeChat is:
You can configure WeeChat in 3 ways: using WeeChat's internal commands; using iset; or by editing the .conf files directly. WeeChat will automatically save settings on exit or when you run
/save, so if you are editing a .conf file in an editor, be sure to run
/reload from the console before exiting, otherwise your changes will be lost.
/set command follows this structure:
You can get a list of all configurable options by typing
/set in the weechat buffer window. Since there are nearly 600 default configurable options, you can search through them with a wildcard syntax:
/set irc.server.* or
/set *server* as an example. You can get help on each option with the
For a more convenient method, install the iset script. If you have weechat 0.3.9 or newer, run:
/script install iset.pl
In older versions, use
/weeget install iset, or download iset.pl into your
~/.weechat/perl/autoload directory manually.
to get a buffer with all configuration options.
The .conf files for WeeChat are saved to
~/.weechat. These files are not commented. Detailed information can be found within the program itself (see Internally above), or WeeChat's user guide.
.weechatdirectory somewhere else (like in your $XDG_CONFIG_HOME), use this option:
$weechat -d $XDG_CONFIG_HOME/weechator set the environment variable
Connecting to a server
Enable by /set irc.look.temporary_servers on
You can connect to a IRC server by using /connect.
Or if there is already a Server setup you can use:
Creating a Server profile
If you plan on connecting to a server more than once it may be beneficial to create a Server.
/server add example irc.example.net/6667
Would create the server example which would connect to irc.example.net on port 6667
See the WeeChat documentation and /help server for more information.
If you're making a server with /server, add the SSL port (usually 6697) and -ssl to the end of the line. For example:
/server add freenode chat.freenode.net/6697 -ssl
You can do the same thing if using /connect.
/connect chat.freenode.net/6697 -ssl
You may also want to change the location where WeeChat looks for trusted authorities (the default value is
%h/ssl/CAs.pem which translates to
/set weechat.network.gnutls_ca_file "/etc/ssl/certs/ca-certificates.crt"
Tips and Tricks
WeeChat can be upgraded without disconnecting from the IRC servers (non-SSL connections only):
This will load the new WeeChat binary and reload the current configuration.
Aliases can be created to simplify commonly executed commands. A nice example is Wraithan's smart filter alias:
First, we need to enable smart filters:
/set irc.look.smart_filter "on"
Next, we will create the sfilter alias:
/alias add sfilter filter add irc_smart_$server_$channel irc.$server.$channel irc_smart_filter *
We can now type
in any buffer, and the smart filter will only be enabled for that buffer.
The following alias will remove a previously enabled smart filter in the current buffer. Add the alias:
/alias add rmsfilter filter del irc_smart_$server_$channel
and execute it by
A new plugin called "exec" has been added, with command
/exec. It will execute external command and can display output to the current buffer with the -o option or locally (default).
Some helpful bindings:
To use ctrl-left/right arrow keys to jump to next/previous words on the input line:
/key bind meta2-1;5D /input move_previous_word /key bind meta2-1;5C /input move_next_word
SSH connection lost when idle
If you're connecting to your WeeChat through a remote shell using SSH, for example running it in screen or tmux you might experience getting disconnected after a while when idle. There are multiple factors in play why this might happen, but the easiest way to change this is to force the connection to be kept alive by appending this to your SSH-configuration on the remote shell.
This has nothing to do with WeeChat itself, but losing connection when idle won't happen with it's alternative irssi by default, and thus is a common situation for those converting to WeeChat.
Or have a look at Mosh.
InstallAUR and enable the script otr.py. Then:
/query <nick> /otr start
Get help on the plugin with:
Slack is a platform for team communication; an IRC on steroids. Thanks to its open API, it is possible to connect to your slack team using weechat.
Once weechat is running, all you have to is add a new server this way:
/server add NAME HOST/6667 -autoconnect -ssl -ssl_dhkey_size=512 -password=PASSWORD -username=USERNAME -nicks=NICK
- NAME is the name you want to give to the server
- HOST is the the Host as provided on the Gateways page of your slack team
- PASSWORD is the Pass as provided on the Gateways page of your slack team
- USERNAME is the User as provided on the Gateways page of your slack team
- NICK is your Slack username.
To upload a file, run this following command from your shell :
curl -F file=@/path/to/file -F channels=CHAN -F token=XXX https://slack.com/api/files.upload
- CHAN is the channel ID as provided on the Gateways page of your slack team
- XXX is the team token as provided on the Gateways page of your slack team
There is a native client for slack: wee-slack
You need to install the python2 librairy websocket-client:
pacman -S python2-websocket-client
Then install the wee-chat plugin into the weechat configuration folder
curl -o ~/.weechat/python/autoload/wee_slack.py https://raw.githubusercontent.com/rawdigits/wee-slack/master/wee_slack.py
/python reload to load the new plugin
You will need an access token. You can grab one at here
Once weechat is running, register your token into weechat:
/set plugins.var.python.slack_extension.slack_api_token [YOUR_SLACK_TOKEN]
To upload a file enter the following command into weechat:
/slack upload [file_path]
To receive desktop notifications for mentions or private messages, the weechat-notify-send script by Petr Zemek can be used.
To install, use:
cd ~/.weechat/python curl -O https://raw.githubusercontent.com/s3rvac/weechat-notify-send/master/notify_send.py ln -s ../notify_send.py autoload/
The script usesand is known to work with both KDE and Gnome.
Mobile device notifications
To receive notifications for mentions or private messages to an Android mobile device, you can use the IrssiNotifier port to WeeChat from here. This script requires a Google Account, and a registration step with the service provider to obtain an API key. Then, install the plugin
cd ~/.weechat/python curl -O https://www.weechat.org/files/scripts/irssinotifier.py ln -s ../irssinotifier.py autoload/
and intialize the API token and end-to-end encryption password in WeeChat
/set plugins.var.python.irssinotifier.api_token your-api-token-from-website /set plugins.var.python.irssinotifier.encryption_password your-password-same-as-in-andoid-app /save
Errors loading plugins
You may see output like the following in the main window after starting weechat:
13:26:10 =!= | Error: unable to load plugin "/usr/lib/weechat/plugins/ruby.so": libruby.so.2.4: cannot open shared object file: No such file or directory 13:26:10 =!= | If you're trying to load a script and not a C plugin, try command to load scripts (/perl, /python, ...) 13:26:10 =!= | Error: unable to load plugin "/usr/lib/weechat/plugins/lua.so": liblua.so.5.3: cannot open shared object file: No such file or directory 13:26:10 =!= | If you're trying to load a script and not a C plugin, try command to load scripts (/perl, /python, ...) 13:26:10 =!= | Error: unable to load plugin "/usr/lib/weechat/plugins/aspell.so": libaspell.so.15: cannot open shared object file: No such file or directory 13:26:10 =!= | If you're trying to load a script and not a C plugin, try command to load scripts (/perl, /python, ...) 13:26:10 =!= | Error: unable to load plugin "/usr/lib/weechat/plugins/tcl.so": libtcl8.6.so: cannot open shared object file: No such file or directory 13:26:10 =!= | If you're trying to load a script and not a C plugin, try command to load scripts (/perl, /python, ...)
The default configuration for weechat attempts to load all plugins found in /usr/lib/weechat/plugins which in this case includes ruby, lua, aspell and tcl. These packages are not required by the weechat package and may not be installed on your machine. There are two options if these errors bother you:
- Install ruby, lua, aspell and/or tcl from the official repositories.
- Or, run
/set weechat.plugin.autoload "*,!ruby,!lua,!aspell,!tcl"which will prevent loading those plugins with a bang (!) prefix.
To access WeeChat's built-in help, simply type
and the help will be displayed in the main buffer (usually buffer 1).