zd-webcli

Web Command-Line Interface for external applications.

Usage no npm install needed!

<script type="module">
  import zdWebcli from 'https://cdn.skypack.dev/zd-webcli';
</script>

README

zd-webcli

NPM
dependencies contributions welcome HitCount

This light-weight and simple (Node.js) application allows you to easily communicate with your server and send commands via the web. It's made to be used on top of your own (Node.js) application, solely for communication and control purposes with that application. It uses an http connection and presents you with a terminal-like web interface when you connect to it. You can then type in your commands and send it to the server. You could for example have it send you status reports back or execute certain practical functions within your application for administration.


Usage

First you will have to make a onData callback function which will handle all incoming data from the web-CLI user(s). Then you have to configure the settings, like setting a password. After everything is set you can use the start() function to start up the Web-CLI

Example

webcli = require("zd-webcli");

webcli.setPassword("SuperSecretPassword"); // Set the password.
webcli.setPort(8080); // Set the port.
webcli.onData(commandHandler); // 'commandHandler' is my own function. (See bottom)

webcli.start(); // Start! (Do after everything is set!)

// My 'onData' callback function
function commandHandler(user, data)
{
    // Parse the data to a format you like.
    const args = data.trim().split(/ +/g);
    const command = args.shift().toLowerCase();

    if(command === "say")
    {
        if(args) user.send(args[0]); // Send a message back to the client.
    }	
    else if(command === "help")
    {
        user.send("List of commands:\n" +
        "\tsay\n");
    }
    else
    {
        user.send("Invalid command. Try `help`.");
    }	
}

After running your application you can connect to the server it's running on with your browser.
For example: http://1.2.3.4:8080/

See Documentation


The Interface

The interface can be used on a mobile, tablet, or PC, with the use of interactive web design.
Interactive interfaces

Login

The login screen is simple.
Login

Communication

In the input you can send commands and arguments that you have made yourself.


From the server you can send responses back in any way you desire.



Documentation

API

*=Essential

Classes


API

*=Essential

--- Main ---

start()*

Start the web-cli!

--- Settings ---

setPassword(password)*

Set the password. | Param | Type | Description | | --- | --- | --- | | password | string | Password to be used. |

setPort(port)

Set the port.
Default: 80
| Param | Type | Description | | --- | --- | --- | | port | number | string | Port to be used. |

setMaxAttempts(maxAttempts)

Set the the max number of login attempts allowed by a connection before getting a timeout. (0=unlimited)
Default: 3
| Param | Type | Description | | --- | --- | --- | | maxAttempts | number | string | Number of logins attempts allowed. |

setMaxUsers(maxUsers)

Set the max number of concurrent users allowed. (0=unlimited)
Default: 1
| Param | Type | Description | | --- | --- | --- | | maxUsers | number | string | Number of concurrent users allowed. |

setWhitelist(file)

Set the path to a file containing IP addresses to be allowed exclusively. (File path is relative to the application's entry point - file should be encoded in UTF-8 - Entries should be separated by lines.)
| Param | Type | Description | | --- | --- | --- | | file | string | Path to file. |

setBlacklist(file)

Set the path to a file containing IP addresses to be denied access invariably. (File path is relative to the application's entry point - file should be encoded in UTF-8 - Entries should be separated by lines.)
| Param | Type | Description | | --- | --- | --- | | file | string | Path to file. |

setLogStatus(set)

Set if the Web-CLI will log to console.
Default: false
| Param | Type | Description | | --- | --- | --- | | set | boolean | Set logging. |

--- Events ---

onData(cb)*

Set the onData event's listener. | Param | Type | Description | | --- | --- | --- | | cb | function | Callback function - takes user{User} and data{string}. |

onConnect(cb)

Set the onConnect event's listener.
| Param | Type | Description | | --- | --- | --- | | cb | function | Callback function - takes connection{Connection}. |

onDisconnect(cb)

Set the onDisconnect event's listener.
| Param | Type | Description | | --- | --- | --- | | cb | function | Callback function - takes connection{Connection}. |

onLogin(cb)

Set the onLogin event's listener.
| Param | Type | Description | | --- | --- | --- | | cb | function | Callback function - takes user{User}. |

onLogout(cb)

Set the onLogout event's listener.
| Param | Type | Description | | --- | --- | --- | | cb | function | Callback function - takes user{User}. |

--- Utility ---

broadcast(message)

Broadcast a message to all current users.
| Param | Type | Description | | --- | --- | --- | | message | function | Message to be sent. |

--- Data ---

connections

Array of all current connections.

users

Array of all current users.


Classes

Connection

Class representing a connection currently active.

.id ⇒ string

Randomly generated ID of the connection.

.ip ⇒ string

IP address of the connection.

.disconnect()

Forcefully close the connection.

User

Class representing a user currently logged in.

.id ⇒ string

Sequentially generated ID of the user.

.connection ⇒ Connection

Corresponding connection of the user.

.logout()

Forcefully log the user out.

.send(message)

Send the user a message. | Param | Type | Description | | --- | --- | --- | | message | string | Message to be sent. |




Useful Info

  • clear is a built in command in the interface. As it implies: it clears the terminal.
  • exit and logout are built in commands in the interface. Use either to logout and exit the interface.
  • The interface has a command history that can be navigated by using the up and down arrow keys in the input.


Trello Board   NPM Package   GitHub Repository