@j-o-r/cli

Command Line Interface (CLI) for Dialogs

This project provides a command line interface (CLI) for creating interactive dialogs. It includes functionalities for handling user input, asking questions, and processing commands. The CLI is designed to be flexible and easy to integrate into various applications.

Features

• Command Parsing: Parse commands from user input with support for parameters.
• Interactive Questions: Ask questions and get responses from the user.
• Role-Based Prompts: Different prompts and colors based on the role (e.g., user, system, assistant).
• Error Handling: Log and display errors.
• Spinner: Display a spinner for long-running operations.

Installation

To use this CLI, you need to have Node.js installed:

npm install @j-o-r/cli

Usage

Basic Example

Here is a simple example demonstrating how to use the CLI to ask questions and handle commands.

1. Create a CLI Handler: Create a file named cli_questions.js and set up the CLI handler.

#!/usr/bin/env node
import cli from './lib/cli.js'; // Adjust the path as necessary

cli.inputHandler = async (s) => {
    if (!s) {
        cli.focus();
        return;
    }
    cli.focus('log');
    cli.write(`user typed: ${s.input}`);
    const name = await cli.question('What is your name?');
    let res = await cli.yesNo(`${name}, are you okay?`);
    cli.focus('assistant');
    cli.write(res ? 'yes!!' : 'no!!!');
    let selected = await cli.select('Why?', ['Nice weather', 'Eggs and bacon']);
    if (selected) {
        cli.write(`Aaah, Because of ${selected}`);
    } else {
        cli.write(`This option wasn't there`);
    }
    cli.focus();
};

cli.abortHandler = () => {
    cli.log('CTRL - s :user wants to abort a process');
};

cli.exitHandler = () => {
    cli.log('CTRL - c :user wants to exit');
    process.exit();
};

cli.focus('log');
cli.write('Just type something');
cli.focus();

2. Run the CLI: Make the script executable and run it.

chmod +x cli_questions.js
./cli_questions.js

Commands

The syntax to distinguess 'user' input from commands are indicated by '>' and '<' characters.

This is normal text >command param1 --param2 -param3 param4 "value"< this is normal text too`

What is this text about: >pasteClipboard<

or directly, without any 'normal' text.

>edit path/to/file<

Keep in mind:

1. There can/should be only ONE command per line
2. Multi line input can not contain commands, the command parsing for multi-line strings is switched off for now.

Implement the execution of commands via the input handler. (example to follow)

Command Parsing Example

Here is an example demonstrating how to parse commands from user input.

1. Create a CLI Command Handler: Create a file named cli_command.js and set up the CLI command handler.

#!/usr/bin/env node

import { suite } from 'uvu';
import * as assert from 'uvu/assert';
import cli from './lib/cli.js'; // Adjust the path as necessary

const test = suite('test cli commands');

cli.abortHandler = () => {
    cli.log('CTRL - s :user wants to abort a process');
};

cli.exitHandler = () => {
    cli.log('CTRL - c :user wants to exit');
    process.exit();
};

test('parse a basic command', async () => {
    return new Promise((resolve) => {
        // Example input
        const input = 'Example >ls -Fla< this is';
        cli.inputHandler = (cmd) => {
            cli.focus();
            cli.write(cmd.input);
            cli.focus('assistant');
            cli.write('Checking the response.');
            assert.equal(cmd.command === 'ls', true);
            assert.equal(cmd.parameters.length, 1);
            assert.equal(cmd.parameters[0], '-Fla');
            resolve();
        };
        cli.input = input;
    });
});

test.run();

2. Run the CLI Command Handler: Make the script executable and run it.

chmod +x cli_command.js
./cli_command.js

API

Cli

• clearLine(): Clear the current line and prompt.
• focus(role): Set the focus to a specific role.
• write(message): Write a message to the console.
• error(err): Write an error message to the console.
• log(any): Log a message.
• clear(): Clear the screen.
• startSpinner(): Start the spinner.
• stopSpinner(): Stop the spinner.
• question(question): Ask a question and resolve the answer.
• yesNo(question): Ask a yes/no question and resolve the answer.
• select(question, choices): Ask a selection question and resolve the answer.
• set inputHandler(handler): Set the input handler.
• set abortHandler(handler): Set the abort handler.
• set exitHandler(handler): Set the exit handler.
• set input(str): Call the input handler directly.
• abort(): Call the abort handler directly.
• exit(): Call the exit handler directly.

License

This project is licensed under the APACHE 2.0 License. See the LICENSE file for details.