Terminal UI (TUI)

A Node.js library for building interactive terminal UIs with a dynamic, class-based command dispatcher.

If you are a developer and want to understand or enhance the library itself, then read DEVELOPMENT.md.

Read on to learn how to install and use the library to create your own TUI.

Install

npm install @dbwebb/tui

Quick start

Create a tui.js in your project:

import { CommandRegistry, TuiShell, BaseCommand } from '@dbwebb/tui';

class ServerCommands extends BaseCommand {
  static descriptions = {
    status: 'status   Show server status',
    restart: 'restart  Restart the server',
  };

  async status() { return 'Server is running.'; }
  async restart() { return 'Server restarted.'; }
}

const registry = new CommandRegistry();
registry.register('server', new ServerCommands());

new TuiShell(registry).start();

Run it:

node tui.js

At the prompt:

> server status
> server restart
> help
> exit

Command groups

Each group is a class that extends BaseCommand. Methods become dispatchable actions.

import { BaseCommand } from '@dbwebb/tui';

export class MyCommands extends BaseCommand {
  static descriptions = {
    greet: 'greet <name>   Say hello',
  };

  async greet(name) {
    return `Hello, ${name}!`;
  }
}

Register it:

registry.register('my', new MyCommands());

Then call it:

> my greet world
Hello, world!

Rules for command methods:

• Must be async
• Return a string (or undefined for no output)
• Names starting with _ are private and will never be dispatched

API

new CommandRegistry()

Holds registered command groups.

• registry.register(name, instance) — register a command group
• registry.dispatch(tokens) — resolve and call a command, returns { ok, message }

new TuiShell(registry)

Interactive readline REPL.

• shell.start() — start the prompt loop
• Built-in commands: help, exit, quit
• Tab-completion for group names and actions

BaseCommand

Base class for all command groups.

• instance.publicMethods() — list of dispatchable method names
• instance.help() — auto-generated help string from static descriptions