Libcli provides a shared C library for including a Cisco-like command-line
interface into other software.

It’s a telnet interface which supports command-line editing, history,
authentication and callbacks for a user-definable function tree.

To compile:

```sh
$ make
$ make install
```

This will install `libcli.so` into `/usr/local/lib`. If you want to change the
location, edit Makefile.

There is a test application built called clitest. Run this and telnet to port
8000.

By default, a single username and password combination is enabled.

```
Username: fred
Password: nerk
```

Get help by entering `help` or hitting `?`.

libcli provides support for using the arrow keys for command-line editing. Up
and Down arrows will cycle through the command history, and Left & Right can be
used for editing the current command line.

libcli also works out the shortest way of entering a command, so if you have a
command `show users | grep foobar` defined, you can enter `sh us | g foobar` if that
is the shortest possible way of doing it.

Enter `sh?` at the command line to get a list of commands starting with `sh`

A few commands are defined in every libcli program:

* `help`
* `quit`
* `exit`
* `logout`
* `history`

Use in your own code:

First of all, make sure you `#include <libcli.h>` in your C code, and link with
`-lcli`.

If you have any trouble with this, have a look at clitest.c for a
demonstration.

Start your program off with a `cli_init()`.
This sets up the internal data structures required.

When a user connects, they are presented with a greeting if one is set using the
`cli_set_banner(banner)` function.

By default, the command-line session is not authenticated, which means users
will get full access as soon as they connect. As this may not be always the best
thing, 2 methods of authentication are available.

First, you can add username / password combinations with the
`cli_allow_user(username, password)` function. When a user connects, they can
connect with any of these username / password combinations.

Secondly, you can add a callback using the `cli_set_auth_callback(callback)`
function. This function is passed the username and password as `char *`, and must
return `CLI_OK` if the user is to have access and `CLI_ERROR` if they are not.

The library itself will take care of prompting the user for credentials.

Commands are built using a tree-like structure. You define commands with the
`cli_register_command(parent, command, callback, privilege, mode, help)` function.

`parent` is a `cli_command *` reference to a previously added command. Using a
parent you can build up complex commands.

e.g. to provide commands `show users`, `show sessions` and `show people`, use
the following sequence:

```c
cli_command *c = cli_register_command(NULL, "show", NULL, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, NULL);
cli_register_command(c, "sessions", fn_sessions, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show the sessions connected");
cli_register_command(c, "users", fn_users, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show the users connected");
cli_register_command(c, "people", fn_people, PRIVILEGE_UNPRIVILEGED, MODE_EXEC, "Show a list of the people I like");
```

If callback is `NULL`, the command can be used as part of a tree, but cannot be
individually run. 

If you decide later that you don't want a command to be run, you can call
`cli_unregister_command(command)`.
You can use this to build dynamic command trees.

It is possible to carry along a user-defined context to all command callbacks
using `cli_set_context(cli, context)` and `cli_get_context(cli)` functions.


You are responsible for accepting a TCP connection, and for creating a
process or thread to run the cli.  Once you are ready to process the
connection, call `cli_loop(cli, sock)` to interact with the user on the
given socket.

This function will return when the user exits the cli, either by breaking the
connection or entering `quit`.

Call `cli_done()` to free the data structures.

