.. _handbook-introduction:


INTRODUCTION
============

Getting Started
~~~~~~~~~~~~~~~

Get the latest tarball from:

    ::

        http://code.google.com/p/jsonbot/downloads/list

Or install from mercurial:

    ::

        hg clone http://jsonbot.googlecode.com/hg jsb
    

Configuration
~~~~~~~~~~~~~

Data and configuratiion files can be found in the datadir which defaults to ~/.jsb (or
another directory if the -d option is used).  You can either use commandline
options to generate the configuration files or run:

    ::

        ./bin/jsb-init

to have them created for you. Look for the config/fleet directory for bot configuration files.


Shell console bot
~~~~~~~~~~~~~~~~~

In the bot dir run the ./bin/jsb command to start the console version of the bot.

    ::

        22:44:11 dev@done:~/dev/0.7/5$ ./bin/jsb
        JSONBOT 0.7 ALPHA1 CONSOLE
        >

If you just want to execute 1 command on the bot, you can do that by giving
it as an argument:

    ::

        22:45:24 dev@done:~/dev/0.7/5$ ./bin/jsb list
        available plugins: 8b, admin, alias, ask, chan, chatlog, choice,
        controlchar, core, count, data, echo, fleet, foo, forward, gatekeeper,
        gcalc, grep, hubbub, idle, ipcalc, irc, karma, kickban, koffie, learn, misc,
        more, mpd, nickserv, not, outputcache, plug, ps, quote, relay, reload,
        remind, restserver, reverse, rss, seen, shop, sort, tail, test, tinyurl, to,
        todo, twitter, udp, uniq, url, urlinfo, user, userstate, watcher, weather,
        welcome, wikipedia, xmpp
 

Shell IRC bot
~~~~~~~~~~~~~

Run the following to make the bot connect to an IRC server:

    ::

        ./bin/jsb-irc -o <userhost of owner> -s <server> -c \<channel>

A configuration file will be generated from the command line opions. If you
already have the configuration files (generated by jsb-init) you can just use (without any options):

    ::

        ./bin/jsb-irc


Shell XMPP bot
~~~~~~~~~~~~~~

Run the following to make the bot connect to an Jabber server:

    ::

        ./bin/jsb-xmpp -o <owner JID> -u <bot JID> -p <password> [-c <conference>] [-s <server>]

Or when configuration files already exist, just run the bot without arguments:

    ::

        ./bin/jsb-xmpp

Conference and server options are optional. Server is take from the -u
option if not provided as a seperate option. 

If you run the bot on a OpenFire server, use the --openfire option 

Plugins
~~~~~~~

To see what plugins are available use the !list command. Use !help <plugin>
to get help on a plugin. 

    ::

        23:03:00 dev@done:~/dev/0.7/5$ ./bin/jsb help misc
        HELP ON MISC misc commands.,     !source - <i> show where to fetch the bot
        source. </i> - examples: source,     !test - <i> give test response. </i> -
        examples:  test



If a plugin is not responding try !plug-enable <plugin>:

    :: 

        23:03:05 dev@done:~/dev/0.7/5$ ./bin/jsb
        JSONBOT 0.7 ALPHA1 CONSOLE
        > !plug-enable misc
        reloading and enabling jsb.plugs.core.misc
        done - plug-enable misc
        > 


otherwise try !admin-boot:

    ::

        23:05:46 dev@done:~/dev/0.7/5$ ./bin/jsb
        JSONBOT 0.7 ALPHA1 CONSOLE
        > !admin-boot
        done - admin-boot
        > 


this will regenerate the callbacks and command indexes. 

You can also use !apro <search> to search for commands:

    ::

        23:01:23 dev@done:~/dev/0.7/5$ ./bin/jsb apro wiki
        commands matching wiki: wikipedia


Commandline Help
~~~~~~~~~~~~~~~~

All the programs have a --help option that shows a help page describing the command line options of the program.