===========
Crate Shell
===========

The shell provides a CLI for CRATE.

If the crate package was installed using `pip` the shell can be started by
invoking `crash` in a terminal.

`crash` by default will try to connect to `localhost:4200`. To connect to
another host use the `connect` command inside the shell or use the `--hosts`
argument when launching the shell.

When you connect to a server that is not reachable or whose hostname cannot be resolved
you will get an error::

    cr> connect 127.0.0.1:65535
    +------------------------+-----------+-----------+--------------------+
    | server_url             | node_name | connected | message            |
    +------------------------+-----------+-----------+--------------------+
    | http://127.0.0.1:65535 | NULL      | FALSE     | Connection refused |
    +------------------------+-----------+-----------+--------------------+
    CONNECT ERROR

    cr> connect null.lol:4200
    +----------------------+-----------+-----------+--------------------------------+
    | server_url           | node_name | connected | message                        |
    +----------------------+-----------+-----------+--------------------------------+
    | http://null.lol:4200 | NULL      | FALSE     | Hostname could no be resolved. |
    +----------------------+-----------+-----------+--------------------------------+
    CONNECT ERROR


Successful connects will give you some information about the servers you connect to::

    cr> connect 127.0.0.1:44209
    +------------------------+-----------+-----------+---------+
    | server_url             | node_name | connected | message |
    +------------------------+-----------+-----------+---------+
    | http://127.0.0.1:44209 | crate     | TRUE      | OK      |
    +------------------------+-----------+-----------+---------+
    CONNECT OK

If you connect to more than one server, the command will succeed
if at least one server is reachable::

    cr> CONNECT 127.0.0.1:44209 null.lol:4295
    +------------------------+-----------+-----------+--------------------------------+
    | server_url             | node_name | connected | message                        |
    +------------------------+-----------+-----------+--------------------------------+
    | http://127.0.0.1:44209 | crate     | TRUE      | OK                             |
    | http://null.lol:4295   | NULL      | FALSE     | Hostname could no be resolved. |
    +------------------------+-----------+-----------+--------------------------------+
    CONNECT OK

Once the shell is connected, SQL statements can be executed simply by entering
them without any special arguments like this::

    cr> SELECT name, kind from locations order by name
    +------------------------------------+-------------+
    | name                               | kind        |
    +------------------------------------+-------------+
    | Aldebaran                          | Star System |
    | Algol                              | Star System |
    | Allosimanius Syneca                | Planet      |
    | Alpha Centauri                     | Star System |
    | Altair                             | Star System |
    | Argabuthon                         | Planet      |
    | Arkintoofle Minor                  | Planet      |
    | Bartledan                          | Planet      |
    | Folfanga                           | Star System |
    | Galactic Sector QQ7 Active J Gamma | Galaxy      |
    | North West Ripple                  | Galaxy      |
    | Outer Eastern Rim                  | Galaxy      |
    | NULL                               | Galaxy      |
    +------------------------------------+-------------+
    SELECT 13 rows in set (... sec)
