# WeeChat quick start guide

Sébastien Helleu
`<flashcode@flashtux.org>`
version 1.1.1, 2015-04-12

## 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. Create an IRC server

The server freenode is created by default on first startup.

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

    /server add oftc irc.oftc.net/6667

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: https://weechat.org/scripts

You can manage scripts in WeeChat with command `/script` (see `/help script` for more info).

## 12. More documentation

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

Enjoy using WeeChat!