path: root/doc/en/weechat_quickstart.en.adoc

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


[[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).

[IMPORTANT]
It is *not recommended* to edit configuration files by hand because WeeChat
may write them at any time (for example on <<command_weechat_quit,/quit>>)
and after any change you must run the command <<command_weechat_reload,/reload>>
(with the risk of losing other changes that were not yet saved with
<<command_weechat_save,/save>>). +
You can use the command <<command_weechat_set,/set>>, which checks the value
and applies immediately the changes.

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

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

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

[NOTE]
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"
----

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 kbd:[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 a server, channel or private buffer (`/close` is an alias for
`/buffer close`):

----
/close
----

[WARNING]
Closing the server buffer will close all channel/private buffers.

Disconnect from server, on the server buffer:

----
/disconnect
----


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

To remove the split:

----
/window merge
----

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

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

For example, to bind kbd:[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-!
----

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

[[more_doc]]
== More documentation

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

Enjoy using WeeChat!