= WeeChat quick start guide
:author: Sébastien Helleu
:email: flashcode@flashtux.org
:lang: en
:toc:


[[start]]
== 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
----

[[help_options]]
== 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.

[[core_vs_plugins]]
== 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.

[[create_irc_server]]
== 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
----

[[irc_server_options]]
== 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
/set irc.server.freenode.ssl_dhkey_size 1024
----

[NOTE]
Freenode does not support the default dhkey size of 2048, so it has to be set
to 1024.

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
----

[[connect_to_irc_server]]
== 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 key[ctrl-x].

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

----
/set irc.look.server_buffer independent
----

[[join_part_irc_channels]]
== 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
----

[[irc_private_messages]]
== 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
----

[[buffer_window]]
== 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
----

[[key_bindings]]
== Key bindings

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

- key[alt-]key[←]/key[→] or key[F5]/key[F6]: switch to previous/next buffer
- key[F7]/key[F8]: switch to previous/next window (when screen is split)
- key[F9]/key[F10]: scroll title bar
- key[F11]/key[F12]: scroll nicklist
- key[Tab]: complete text in input bar, like in your shell
- key[PgUp]/key[PgDn]: scroll text in current buffer
- key[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 key[alt-k] to find key codes.

For example, to bind key[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
----

[[plugins_scripts]]
== 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).

[[more_doc]]
== More documentation

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

Enjoy using WeeChat!
