@dgtlntv/protostar v0.0.1

Proto* is a tool for creating interactive CLI prototypes using a simple JSON configuration file. The tool generates a website that emulates a terminal, with only the CLI defined in the configuration file being available. It's designed for quick and easy creation of CLI prototypes, enabling rapid iterations. The tool automatically deploys to GitHub Pages, allowing prototypes to be easily shared. This makes it suitable for user testing, as users can access the prototype through a simple link rather than having to install anything.

Prerequisites

You have to have git and node installed.

Setup and Usage

2. Clone the newly created repository to your local computer either with an app like Github desktop or by running the following command:

git clone https://github.com/your-username/cli-prototype.git
cd cli-prototype

3. In the cloned repository install the dependencies:

npm install

4. Run the development server:

npm run dev

5. Open the provided URL in your web browser to interact with your CLI prototype.

Deployment

This project is set up to deploy automatically to GitHub Pages using GitHub Actions:

Using Protostar as a Library

In addition to using Protostar as a standalone CLI prototyping tool, you can also integrate it as a library in your JavaScript projects:

Installation

npm install protostar

Usage as a library

// Import the required styles
import "@xterm/xterm/css/xterm.css"
import "./styles.css"

// Import the Terminal component
import { Terminal } from "protostar"

// Import your commands configuration
import commandsData from "./commands.json"

// Initialize the terminal when the DOM is ready
document.addEventListener("DOMContentLoaded", () => {
    const terminal = new Terminal(
        document.getElementById("terminal"),
        commandsData
    )
})

Customizing Your CLI

This prototyping tool is build in a way so that the only file you need to change to customize your CLI prototype is the src/commands.json file. The general schema of the commands.json is:

{
    // Welcome message for the CLI prototype
    welcome: "Welcome to My CLI! Type 'help' for available commands.",

    // The global variables you can read and write accross commands
    variables: {
        username: "dgtlntv",
        isLoggedIn: "false",
    },
    commands: {
        // The commands available in the CLI prototype
    },
}

• welcome is optional. It defines a welcome message that is output when the CLI is loaded for the first time.
• variables is optional as well and can be used to define variables that can be set and checked by commands. For example, through them we can prescribe a specific command sequence.
• The commands of the CLI are defined in the commands object.

Commands

Command name

The command name with which the command can be called is the key of the command object. In this example we are creating a register command:

{
    commands: {
        register: {
            // Command content
        },
    },
}

Description

The description is shown in the automatically generated help message.

{
    commands: {
        register: {
            description: "This command registers a new account with the service.",
        },
    },
}

Alias

An alias allows you to call the same command with a different command name. Can either be a single string or an array of strings. In the following example the user could call the same registercommand with enrol or signup now.

{
    commands: {
        register: {
            alias: ["enrol", "signup"],
        },
    },
}

Example

The example will be used to provide example usages of a command in the automatically generated help message. Can be a single example command, description or an array of such examples.

{
    commands: {
        register: {
            example: [
                "register email@example.com",
                "Register a new account with the email@example.com email.",
            ],
        },
    },
}

Positional arguments

Positional arguments in commands can be either required or optional. Required positional arguments are denoted as <email>, while optional arguments are represented as [username].

{
    commands: {
        "register <email> [username]": {
            // Command content
        },
    },
}

The | character allows you to specify aliases for positional arguments.

{
    commands: {
        "register <email | username>": {
            // Command content
        },
    },
}

The last positional argument can optionally accept an array of values, by using the .. operator:

{
    commands: {
        "register <email> [..socialUrls]": {
            // Command content
        },
    },
}

Under positional the positional argument of a command are defined. You can use the following fields to describe the positional arguments:

{
    commands: {
        "register <email>": {
            positional: {
                email: {
                    alias: "username",
                    // choice and default don't really make sense in this example, but is an available configuration
                    // "choices": [
                    //     "choice1",
                    //     "choice2",
                    //     "choice3"
                    // ],
                    // "default": "defaultOption",
                    demandOption: true,
                    description: "The email to register your account with",
                    type: "string",
                },
            },
        },
    },
}

Options / flags

Under options the flags (eg. --flag) of a command are defined. You can use the following fields to describe the options/flags:

{
    commands: {
        register: {
            options: {
                password: {
                    alias: ["pwd", "pw"],
                    // choice and default don't really make sense in this example, but is an available configuration
                    // "choices": [
                    //     "choice1",
                    //     "choice2",
                    //     "choice3"
                    // ],
                    // "default": "defaultOption",
                    // "defaultDescription": "The description for the default option",
                    demandOption: true,
                    description: "The password for your account",
                    group: "Login credentials",
                    hidden: false,
                    nargs: 1,
                    requiresArg: true,
                    type: "string",
                },
            },
        },
    },
}

Sub-commands

If you want to chain multiple commands you can nest commands under commands. The commands defined under commands allow for the exact same configuration as a root command.

{
    commands: {
        register: {
            commands: {
                user: {
                    // Command content
                },
                serviceaccount: {
                    // Command content
                },
            },
        },
    },
}

Handler

Under handler the response to a command is defined. The handler accepts the components available in the CLI prototyping tool. The available components are the following:

The handler accepts either a single component:

{
    commands: {
        register: {
            handler: {
                component: "text",
                output: "Registered successfully",
            },
        },
    },
}

Or an array of components:

{
    commands: {
        register: {
            handler: [
                {
                    component: "text",
                    output: "Registering in progress...",
                    duration: 5000,
                },
                {
                    component: "text",
                    output: "Registered successfully",
                },
            ],
        },
    },
}

The following section explains each available component more in depth:

Components

A component corresponds to something that can happen as a reaction to a command. Multiple components can be linked together to happen in sequence. See the handler documentation.

Text

The simplest of the components is the text component. It simply prints text to the terminal, while optionally waiting for some time after printing the text to the terminal.

{
    commands: {
        register: {
            handler: [
                {
                    component: "text",
                    output: "Registering in progress...",
                    duration: 2000,
                },
                {
                    component: "text",
                    output: "Registered successfully",
                },
            ],
        },
    },
}

Progress bar

The progress bar component renders a progress bar in the terminal, showing a task's completion over time.

{
    commands: {
        install: {
            handler: {
                component: "progressBar",
                output: "Installing dependencies...",
                duration: 2000,
            },
        },
    },
}

Spinner

The spinner component displays an animated spinner in the terminal, indicating that a process is ongoing.

{
    commands: {
        process: {
            handler: {
                component: "spinner",
                output: ["Processing", "Please wait", "Almost done"],
                duration: 2000,
                conclusion: "succeed",
            },
        },
    },
}

Table

The table component renders a formatted table in the terminal.

{
    commands: {
        list: {
            handler: {
                component: "table",
                output: [
                    ["Name", "Age", "City"],
                    ["John", "30", "New York"],
                    ["Alice", "25", "London"],
                ],
                colWidths: [10, 5, 15],
            },
        },
    },
}

Conditional

The conditional component allows for branching logic based on a condition.

The output object should contain the following fields.

{
    commands: {
        check: {
            handler: {
                component: "conditional",
                output: {
                    if: "isLoggedIn == 'true'",
                    then: {
                        component: "text",
                        output: "Welcome back!",
                    },
                    else: {
                        component: "text",
                        output: "Please log in first.",
                    },
                },
            },
        },
    },
}

Variable

The variable component allows setting global variables that can be used across commands. For the setting of the variable to be succesfull it needs to be initialized as a global variable in the CLIs global variables.

{
    commands: {
        login: {
            handler: [
                {
                    component: "text",
                    output: "Before setting the variables username is {{username}} and isLoggedin is {{isLoggedIn}}",
                },
                {
                    component: "variable",
                    output: {
                        username: "john_doe",
                        isLoggedIn: "true",
                    },
                },
                {
                    component: "text",
                    output: "After setting the variables username is {{username}} and isLoggedin is {{isLoggedIn}}",
                },
            ],
        },
    },
}

AutoComplete

The autoComplete component provides a prompt that auto-completes as the user types.

{
    commands: {
        search: {
            handler: {
                component: "autoComplete",
                name: "query",
                message: "Search for a fruit:",
                choices: ["Apple", "Banana", "Cherry", "Date", "Elderberry"],
                limit: 3,
                footer: "Use arrow keys to navigate",
            },
        },
    },
}

BasicAuth

The basicAuth component prompts for username and password authentication.

{
    commands: {
        login: {
            handler: {
                component: "basicAuth",
                name: "auth",
                message: "Please enter your credentials:",
                username: "admin",
                password: "secret",
                showPassword: false,
            },
        },
    },
}

Confirm

The confirm component prompts to confirm or deny a statement.

{
    commands: {
        delete: {
            handler: {
                component: "confirm",
                name: "confirmDelete",
                message: "Are you sure you want to delete this item?",
                initial: false,
            },
        },
    },
}

Form

The form component prompts for multiple values on a single terminal screen.

Each choice in the choices array should have the following properties:

{
    commands: {
        register: {
            handler: {
                component: "form",
                name: "userInfo",
                message: "Please enter your information:",
                choices: [
                    {
                        name: "username",
                        message: "Username:",
                        initial: "user123",
                    },
                    {
                        name: "email",
                        message: "Email:",
                    },
                ],
            },
        },
    },
}

Input

The input component prompts for user input.

{
    commands: {
        name: {
            handler: {
                component: "input",
                name: "username",
                message: "What's your name?",
                initial: "Anonymous",
            },
        },
    },
}

Invisible

The invisible component prompts for user input, hiding it from the terminal.

{
    commands: {
        password: {
            handler: {
                component: "invisible",
                name: "password",
                message: "Enter your password:",
            },
        },
    },
}

List

The list component prompts for a list of values, created by splitting user input.

{
    commands: {
        tags: {
            handler: {
                component: "list",
                name: "tags",
                message: "Enter tags (comma-separated):",
            },
        },
    },
}

MultiSelect

The multiSelect component allows selection of multiple items from a list of options.

Each choice in the choices array should have the following properties:

{
    commands: {
        features: {
            handler: {
                component: "multiSelect",
                name: "features",
                message: "Select desired features:",
                choices: [
                    { name: "Auto-save", value: "autosave" },
                    { name: "Dark mode", value: "darkmode" },
                    { name: "Notifications", value: "notifications" },
                ],
                limit: 2,
            },
        },
    },
}

Number

The number component prompts for a numeric input.

{
    commands: {
        age: {
            handler: {
                component: "number",
                name: "age",
                message: "Enter your age:",
            },
        },
    },
}

Password

The password component prompts for a password, masking the input in the terminal.

{
    commands: {
        password: {
            handler: {
                component: "password",
                name: "newPassword",
                message: "Enter new password:",
            },
        },
    },
}

Quiz

The quiz component presents multiple-choice quiz questions.

{
    commands: {
        quiz: {
            handler: {
                component: "quiz",
                name: "capitalQuiz",
                message: "What is the capital of France?",
                choices: ["London", "Berlin", "Paris", "Madrid"],
                correctChoice: 2,
            },
        },
    },
}

Survey

The survey component prompts for user feedback on a list of questions using a defined scale.

Each item in the scale array should have:

Each item in the choices array should have:

{
    commands: {
        feedback: {
            handler: {
                component: "survey",
                name: "userSatisfaction",
                message: "Please rate your experience:",
                scale: [
                    { name: "1", message: "Strongly Disagree" },
                    { name: "3", message: "Neutral" },
                    { name: "5", message: "Strongly Agree" },
                ],
                choices: [
                    {
                        name: "easeOfUse",
                        message: "The product was easy to use",
                    },
                    {
                        name: "features",
                        message: "The product had all the features I needed",
                    },
                ],
            },
        },
    },
}

Scale

The scale component is a compact version of the Survey prompt, using a Likert Scale for quick feedback.

Each item in the scale array should have:

Each item in the choices array should have:

{
    commands: {
        feedback: {
            handler: {
                component: "scale",
                name: "productRating",
                message: "Rate our product:",
                scale: [
                    { name: "1", message: "Poor" },
                    { name: "3", message: "Average" },
                    { name: "5", message: "Excellent" },
                ],
                choices: [
                    {
                        name: "overall",
                        message: "Overall satisfaction",
                        initial: 3,
                    },
                    { name: "support", message: "Customer support" },
                ],
            },
        },
    },
}

Select

The select component prompts for selecting from a list of options.

The choices can be either an array of strings or an array of objects with name and value properties:

{
    commands: {
        color: {
            handler: {
                component: "select",
                name: "favoriteColor",
                message: "Choose your favorite color:",
                choices: [
                    { name: "Red", value: "red" },
                    { name: "Blue", value: "blue" },
                    { name: "Green", value: "green" },
                ],
            },
        },
    },
}

Sort

The sort component prompts for sorting items in a list.

{
    commands: {
        tasks: {
            handler: {
                component: "sort",
                name: "taskOrder",
                message: "Sort these tasks by priority:",
                choices: [
                    "Fix bugs",
                    "Implement new feature",
                    "Write documentation",
                    "Refactor code",
                ],
            },
        },
    },
}

Snippet

The snippet component prompts for replacing placeholders in a snippet of code or text.

Each item in the fields array should have:

{
    commands: {
        generate: {
            handler: {
                component: "snippet",
                name: "package",
                message: "Fill out the fields in package.json",
                fields: [
                    { name: "name", message: "Name of the package" },
                    {
                        name: "description",
                        message: "Description of the package",
                    },
                    { name: "version", message: "Version of the package" },
                    { name: "username", message: "Your username" },
                    { name: "author_name", message: "Your name" },
                    {
                        name: "license",
                        message: "The license of the package",
                    },
                ],
                template: '{\n  "name": "${name}",\n  "description": "${description}",\n  "version": "${version}",\n  "homepage": "https://github.com/${username}/${name}",\n  "author": "${author_name} (https://github.com/${username})",\n  "repository": "${username}/${name}",\n  "license": "${license:ISC}"\n}\n',
            },
        },
    },
}

Toggle

The toggle component prompts for toggling between two values.

{
    commands: {
        notifications: {
            handler: {
                component: "toggle",
                name: "notificationsEnabled",
                message: "Enable notifications?",
                enabled: "Yes",
                disabled: "No",
            },
        },
    },
}