.. _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 ` 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:: supybot: list 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:: supybot: list Misc 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:: supybot: help help user: (help [] []) -- This command gives a useful description of what does. 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. supybot: help list user: (list [--unloaded] []) -- 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. supybot: help load user: (load ) -- Loads the 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:: supybot: help config list user: (config list ) -- Returns the configuration variables available under the given configuration . 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:: 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. ` 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:: help identify (identify ) -- Identifies the user as . 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:: identify myowneruser myuserpassword 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 ` section for details on how to do that). To find your NickServ account name, run ``/whois ``, 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, ```` refers to your bot user, and ```` refers to your NickServ account name:: @help nickauth nick add (nick add [] ) -- Add to the list of nicks owned by the on the . You have to register this nick to the network services to be authenticated. defaults to the current network. To add the NickServ account "Mikaela" to a bot account of the same name:: @nickauth nick add Mikaela Mikaela 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 `_ and `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:: @whoami I don't recognize you. You can messsage me either of these two commands: "user identify " to log in or "user register " to register. @nickauth auth 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:: @help hostmask add (hostmask add [] [] []) -- Adds the hostmask to the user specified by . The may only be required if the user is not recognized by hostmask. is also not required if an owner user is giving the command on behalf of some other user. If is not given, it defaults to your current hostmask. If 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 ` 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 hostmask add myuser *!*@mycloak The operation succeeded. On shared hosts that implement the `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 hostmask add myuser *!myident@myhost 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 to the bot as an owner user `. Loading plugins is done with the ``load`` command:: @help load user: (load ) -- Loads the 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:: @load Games The operation succeeded. To unload a plugin, there is a corresponding ``unload`` command:: @unload Games The operation succeeded. To find plugins to load, consult the :ref:`Built-in plugins reference ` or the Plugins list on `limnoria.net `_. .. _help-syntax: Understanding the help syntax ============================= This section further explains the help syntax given by the ``help`` command. Some examples: help [] [] This is the help of :ref:`command-plugin-help`. The chevrons mean you have to replace and by a plugin name and a command name. The square brackets mean the arguments they wrap are **optional**. So, the following commands are correct:: help help PluginName help PluginName CommandName help CommandName ping takes no arguments This is the help for :ref:`command-misc-ping`. I think it is clear enough. join [] This is the help for :ref:`command-admin-join`. It requires a channel name, and the channel key is optional. These two commands are ok:: join #limnoria join #limnoria MySecretKey utilities last [ ...] 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. Pagination: Getting More From Your Limnoria =========================================== Limnoria automatically splits messages that are too long for IRC into multiple chunks (aka "mores"). By default, it will send only the first chunk, followed by ``(X more messages)``. To view the remaining parts of a response, run the ``more`` command, repeating it as necessary. Example:: $config default supybot.replies.genericNoCapability jemfinch: 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) $more jemfinch: that no commands are allowed unless explicitly in your capabilities. Either way, you can't do what you want to do. Chunked messages are stored by user, and you can view "mores" directed at some else by specifying their nick in the command, e.g. ``more jemfinch``. After doing this, any further responses are redirected to you, so they can be displayed via ``more`` (without any extra argument). If you want the bot to display more pages automatically, you can also :ref:`configure ` the following option:: @config help reply.mores.instant Determines how many mores will be sent instantly (i.e., without the use of the more command, immediately when they are formed). Defaults to 1, which means that a more command will be required for all but the first chunk. (Current value: 5) Final Word ========== You should now have a solid foundation for using Limnoria! In summary, use the ``list`` command to see what plugins your bot has loaded and what commands are in those plugins, the ``help`` command to see how to use a command, and the ``more`` command to continue a long response from the bot. Do be sure to read the rest of the documentation, and visit #limnoria on irc.libera.chat if you run into any trouble!