Limnoria-doc/use/getting_started.rst

.. _getting-started:

*************************************
Getting Started with Limnoria/Supybot
*************************************

.. highlight:: irc

Introduction
============

Ok, so you've decided to try out Limnoria.  That's great!  The more people who
use Limnoria, the more people can submit bugs and help us to make it the best
IRC bot in the world :)

At this point, we assume you've already followed the steps to
:ref:`install and configure <use-install>` Limnoria, and that the bot has
connected to the network you specified.

When the bot is in a channel, it will respond by default to messages prefixed by
its nick (e.g. ``supybot: echo hi``), or any prefixes you configured inside the
wizard (e.g. ``@echo hi``). If you haven't told it to join any channels,
you can also send it direct messages, in which case no prefix is required.

Finding the bot's commands
==========================

Limnoria uses a two tier system for its commands, where each command is
registered under a plugin. The first step to navigating Limnoria is to run
``list``, which will show you all the plugins loaded::

    <user> supybot: list
    <supybot> Admin, Channel, ChannelLogger, Config, Misc, Network, Owner, Plugin, User, and Utilities

Replacing 'supybot' with the actual name you picked for your bot, of course.
At least `Admin`, `Channel`, `Config`, `Misc`, `Owner`, and `User` should be
there; if you used ``supybot-wizard`` to create your configuration file you may
have many more plugins loaded.  The ``list`` command can then be used to list the
commands in a given plugin::

    <user> supybot: list Misc
    <supybot> user: apropos, clearmores, completenick, help, last, list, more, noticetell, ping, source, tell, and version

This lists all the commands in the `Misc` plugin.  If you want to see the help
for a specific command, you can then use the help command::

    <user> supybot: help help
    <supybot> user: (help [<plugin>] [<command>]) -- This command gives a useful description of what <command> does. <plugin> is only necessary if the command is in more than one plugin. You may also want to use the 'list' command to list all available plugins and commands.
    <user> supybot: help list
    <supybot> user: (list [--unloaded] [<plugin>]) -- Lists the commands available in the given plugin. If no plugin is given, lists the public plugins available. If --unloaded is given, it will list available plugins that are not loaded.
    <user> supybot: help load
    <supybot> user: (load <plugin>) -- Loads the plugin <plugin> from any of the directories in conf.supybot.directories.plugins; usually this includes the main installed directory and 'plugins' in the current directory.

Sometimes more than one plugin will register a given command; for instance, the
``list`` command exists in both the Misc and Config plugins (both loaded by
default).  ``list``, in this case, defaults to the Misc plugin, but you may want
to get the help for the list command in the Config plugin.  In that case,
you can prefix your command with the name of the plugin::

    <user> supybot: help config list
    <supybot> user: (config list <group>) -- Returns the configuration variables available under the given configuration <group>. If a variable has values under it, it is preceded by an '@' sign.

Anytime your bot tells you that a given command is defined in several plugins,
you'll need to use this "plugin command" syntax to choose which
plugin's command you wish to call.  For instance, if you wanted to call the
Config plugin's ``list`` command, then you'd need to run::

    <user> supybot: config list

Rather than just ``list``.

.. _login-to-bot:

Logging in to Limnoria
======================

.. note::
    For making the bot to identify to services, please see
    :ref:`identifying to services. <identifying-to-services>`

Most administrative tasks in Limnoria (loading plugins, adding networks) require
you to be logged in to the bot as an ``owner`` user. If you used
``supybot-wizard`` to configure the bot, you have probably added an owner user
already. If not, shut off the bot and run the ``supybot-adduser`` script to
create a user, and give yourself the ``owner`` capability when it prompts you
to do so.

To log in to the bot, use the ``identify`` command. This must be sent in a
private message (i.e. ``/query``) to the bot, to avoid leaking your password
to a channel::

    <user> help identify
    <supybot> (identify <name> <password>) -- Identifies the user as <name>. This command (and all other commands that include a password) must be sent to the bot privately, not in a channel.

Replacing "myowneruser" and "myuserpassword" with your login details, you should
run::

    <user> identify myowneruser myuserpassword
    <supybot> The operation succeeded.

Once you are logged in as an owner user, you can run commands that require
privileges. Many such administrative commands are located in the *Owner* and
*Admin* plugins.

Automatic login (optional)
--------------------------

If you wish to make managing the bot easier, there are a few ways to log in to
the bot automatically.

Automatic login using network services (NickAuth)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

On IRC networks that provide a modern NickServ implementation,
Limnoria supports associating your bot account with a services account. This is
often the easiest method, as it does not involve configuring hostmasks.

To use this, you first need to load the **NickAuth** plugin (see the
:ref:`loading plugins <loading-plugins>` section for details on how to do that).

To find your NickServ account name, run ``/whois <yournick>``, and you should see
some output like this::

    [Mikaela] is logged in as Mikaela

NickAuth logins are managed using the ``nickauth nick add`` and ``nickauth nick remove``
commands. For clarity, ``<user>`` refers to your bot user, and ``<nick>`` refers
to your NickServ account name::

    <user> @help nickauth nick add
    <Limnoria> (nick add [<network>] <user> <nick>) -- Add <nick> to the list of nicks owned by the <user> on the <network>. You have to register this nick to the network services to be authenticated. <network> defaults to the current network.

To add the NickServ account "Mikaela" to a bot account of the same name::

    <Mikaela> @nickauth nick add Mikaela Mikaela
    <Limnoria> OK.

On most networks, NickAuth will automatically activate when you log in to your
services account or join a channel the bot is in. Note that this requires the
`extended-join <https://ircv3.net/specs/extensions/extended-join>`_ and
`WHOX <https://ircv3.net/specs/extensions/whox>`_ IRCv3 features to be supported
by the IRC network.

In places where this does not work, you can manually trigger a login
attempt using the ``nickauth auth`` command::

    <Guest45020> @whoami
    <Limnoria> I don't recognize you. You can messsage me either of these two commands: "user identify <username> <password>" to log in or "user register <username> <password>" to register.
    <Guest45020> @nickauth auth
    <Limnoria> You are now authenticated as Mikaela.

Automatic login using a hostmask
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

An alternative to NickAuth that works everywhere is automatic login using your
IRC hostmask (``nick!user@host``). This may be more work to set up as there is
no one-size-fits-all hostmask to match someone; the best approach depends
on the network you're on and the type of host you are connecting from.

Hostmask login is configured using the ``user hostmask add`` and
``user hostmask remove`` commands::

    <user> @help hostmask add
    <Limnoria> (hostmask add [<name>] [<hostmask>] [<password>]) -- Adds the hostmask <hostmask> to the user specified by <name>. The <password> may only be required if the user is not recognized by hostmask. <password> is also not required if an owner user is giving the command on behalf of some other user. If <hostmask> is not given, it defaults to your current hostmask. If <name> is not given, it defaults to your currently identified name. This message must be sent to the bot privately (not on a channel) since it may contain a password.

.. warning::
    Before adding a hostmask, double check that it is specific enough to only
    match *you*. Giving permissions to wide hostmasks (e.g. ``nick!user@*``) is
    a security risk, and could allow others to hijack your bot.

If you're on a network that provides unique :ref:`cloaks/vhosts <cloak-examples>`
based on your username, or have an otherwise dedicated static IP
(e.g. on a server not shared with other people), you can use the "host" part of
your hostmask for logging in::

    <user> user hostmask add myuser *!*@mycloak
    <Limnoria> The operation succeeded.

On shared hosts that implement the `IDENT protocol <https://en.wikipedia.org/wiki/Ident_protocol>`_,
you may want to add the username / ident field to the hostmask as well.
Note that this only works well if the network also implements IDENT checking;
otherwise, anyone can connect with anything in the username field::

    <user> user hostmask add myuser *!myident@myhost
    <Limnoria> The operation succeeded

.. _cloak-examples:

*mycloak* at Libera.chat, for instance, is usually in the format ``user/accountname``.
On other networks, you may be able to request cloaks using HostServ (``/msg HostServ help``)
or by asking a network operator. Note: OFTC is exception, and uses
``/msg NickServ set cloak on`` instead.

.. _loading-plugins:

Loading Plugins
===============

.. note::
    To load plugins, you first need to be :ref:`logged in the the bot <login-to-bot>`.

Loading plugins is done with the ``load`` command::

    <user> @help load
    <Limnoria> user: (load <plugin>) -- Loads the plugin <plugin> from any of the directories in conf.supybot.directories.plugins; usually this includes the main installed directory and 'plugins' in the current directory.

For example, to load the *Games* plugin, run::

    <user> @load Games
    <Limnoria> The operation succeeded.

To unload a plugin, there is a corresponding ``unload`` command::

    <user> @unload Games
    <Limnoria> The operation succeeded.

To find plugins to load, consult the :ref:`Built-in plugins reference <builtin-plugins-reference>`
or the Plugins list on `limnoria.net <https://limnoria.net/plugins.xhtml>`_.

Understanding the help syntax
=============================

The syntax of a command describes how to run a command.
The syntax is given by the help command.
Some examples:

help [<plugin>] [<command>]
    This is the help of :ref:`command-plugin-help`.

    The chevrons mean you have to replace <plugin> and <command> by a plugin
    name and a command name.

    The brackets mean the argument they wrap is **optional**.

    So, the fellowing commands are correct::
    
        <user> help
        <user> help PluginName
        <user> help PluginName CommandName
        <user> help CommandName

ping takes no arguments
    This is the help for :ref:`command-misc-ping`.

    I think it is clear enough.

join <channel> [<key>]
    This is the help for :ref:`command-admin-join`.
    
    It requires a channel name, and the channel key is optional.

    This two commands are ok::

        <user> join #limnoria
        <user> join #limnoria MySecretKey

utilities last <text> [<text> ...]
    This is the help for :ref:`command-utilities-last`.
    By the way, there is another ``last`` command in the `Misc` plugin, which
    doesn't do the same thing, that's why you need to give the plugin name.

    You have to give at least one argument, but you can give as many as you
    wish.

Getting More From Your Limnoria
===============================

Another command you might find yourself needing somewhat often is the 'more'
command.  The IRC protocol limits messages to 512 bytes, 60 or so of which
must be devoted to some bookkeeping.  Sometimes, however, Limnoria wants to
send a message that's longer than that.  What it does, then, is break it into
"chunks" and send the first one, following it with ``(X more messages)`` where
X is how many more chunks there are.  To get to these chunks, use the `more`
command.  One way to try is to look at the default value of
`supybot.replies.genericNoCapability` -- it's so long that it'll stretch
across two messages::

    <jemfinch|lambda> $config default
                      supybot.replies.genericNoCapability
    <lambdaman> jemfinch|lambda: You're missing some capability
                you need. This could be because you actually
                possess the anti-capability for the capability
                that's required of you, or because the channel
                provides that anti-capability by default, or
                because the global capabilities include that
                anti-capability. Or, it could be because the
                channel or the global defaultAllow is set to
                False, meaning (1 more message)
    <jemfinch|lambda> $more
    <lambdaman> jemfinch|lambda: that no commands are allowed
                unless explicitly in your capabilities. Either
                way, you can't do what you want to do.

So basically, the bot keeps, for each person it sees, a list of "chunks" which
are "released" one at a time by the `more` command.  In fact, you can even get
the more chunks for another user: if you want to see another chunk in the last
command jemfinch gave, for instance, you would just say `more jemfinch` after
which, his "chunks" now belong to you.  So, you would just need to say `more`
to continue seeing chunks from jemfinch's initial command.

Final Word
==========

You should now have a solid foundation for using Limnoria.  You can use the
`list` command to see what plugins your bot has loaded and what commands are
in those plugins; you can use the 'help' command to see how to use a specific
command, and you can use the 'more' command to continue a long response from
the bot.  With these three commands, you should have a strong basis with which
to discover the rest of the features of Limnoria!

Do be sure to read our other documentation and make use of the resources we
provide for assistance; this website and, of course, #limnoria on
irc.libera.chat if you run into any trouble!