Rawcmd allows for building command-line user interfaces in NodeJS. It's a lightweight and open-source framework, written with TypeScript. It's actively maintained, well tested and already used in production environments. The source code is available on GitHub where you can also find our issue tracker.

Rawcmd represents a scaffold for creating reach command-line user interfaces in NodeJS. The purpose of this framework is to provide the logic and methods for building custom command-line utilities.

Run the command below to install the package.

$ npm install --save @rawcmd/core
$ npm install --save @rawcmd/typewriters // OPTIONAL

This package uses promises thus you need to use Promise polyfill when promises are not supported.

Below we explain some of the most important features that this framework provides. Please check the API section to see a complete list of features.

Command represents the entry point of your command-line program.

import { Command } from '@rawcmd/core';

const command = new Command({
  resolver() {
    console.log('Hello World!');
  },
});

command.perform(); // prints "Hello World!"

By nesting commands we can create a tree of commands.

const command = new Command({ // entry point (root)
  commands: [
    new Command({ // first level
      name: 'list',
      resolver() {
        console.log('List all!');
      },
      commands: [
        new Command({ // second level
          name: 'latest',
          resolver() {
            console.log('List latest!');
          },
        }),
      ],
    }),
  ],
});

command.perform('list'); // prints "List all!"
command.perform('list', 'latest'); // prints "List latest!"

Every command accepts options which we can use to adjust command execution. We can apply parsers and validators to each option to make sure the resolver receives expected input data. In case one of validators fail, the resolver throws ValidationError class instance.

const command = new Command({
  options: [
    {
      name: 'name',
      alias: 'n',
      parse: { // check @rawmodel/parsers for predefined parsers
        resolver(v) { return `${v}` }, // transform value to string
      },
      validate: [ // check @rawmodel/validators for predefined validators
        {
          code: 4220001,
          resolver() { return false; }, // return `false` so validation fails
        },
      ],
    },
  ],
  resolver(input) {
    console.log(input); // => { "options": { "name": "John" }, "tail": "arg1 arg2" }
  },
});

command.perform('--name=John', '--', 'arg1', 'arg2').catch((error) => {
  console.log(error); // => { "code": 4220001, "name": "ValidationError", "message": "Validation failed." }
});

The validation is handled by the powerful RawModel framework where you will find more details regarding data validation.

Every command provides methods for printing messages to the output stream. By default the output stream is set to process.stdout.

const command = new Command({
  resolver() {
    this.print('Hello World!'); // prints message with EOL
  },
});

Messages can be formated through different typewriters which can be found in @rawcmd/typewriters package.

import { textTypewriter } from '@rawcmd/typewriters'; 

const typewriteGreen = textTypewriter({
  bold: true,
  color: TextColor.GREEN,
});

const command = new Command({
  resolver() {
    this.write( // prints "100%" as strong green text
      typewriteGreen('100'),
      typewriteGreen('%'),
    );
    this.break(); // prints EOL
  },
});

Errors should be triggered directly within resolver and handled outside command class.

import { RuntimeError } from '@rawcmd/core';

const command = new Command({
  resolver() {
    throw new RuntimeError(500001);
  },
});

command.perform().catch((error) => {
  command.print('Error', error.message);
});

Beside the ValidationError which we already mentioned above, RuntimeError can be thrown when an error accures. It's advised that you use your custom errors which extend GenericError class.

TODO

NOTE: This section covers only the end-user related classes and methods. Please read the source code to explore more details.

Command(recipe, config)

Command class for defining executable command.

Command.prototype.name: String

Returns command name.

Command.prototype.description: String

Returns command description.

Command.prototype.getAncestors(): Command[]

Returns a list of all parent command instances.

Command.prototype.getContext(): Context

Returns custom context defined at initialization time.

Command.prototype.getParent(): Command

Returns parent command instance.

Command.prototype.getTypewriter(): Typewriter

Returns typewriter class instance.

Command.prototype.perform(...args): Promise

Performs a command based on the provided command-line arguments.

Command.prototype.write(...messages): Command

Appends outptu stream with messages.

Command.prototype.print(...messages): Command

Writes messages to outptu stream with EOL at the end.

Command.prototype.break(): Command

Writes EOL to outptu stream.

Command.prototype.spin(message): Command

Writes a message to outptu stream as spinner animation.

EOL: String

Holds a new-line character.

commandsTypewriter(options): Function(command)

Returns a function which builds a string showing a list of all available sub commands with descriptions.

contentsTypewriter(options): Function(data)

Returns a function which builds an arbitrary table of contents string with names and decriptions

helpTypewriter(options): Function(data)

Returns a function which builds a string describing command abilities and other useful information.

linksTypewriter(options): Function(command)

Returns a function which builds a string representing a list of all usefull support references and links.

optionsTypewriter(options): Function(command)

Returns a function which builds a string representing a list of all available command options with descriptions.

rowTypewriter(columns, options): Function(data)

Converts data to stringified table.

import { rowTypewriter } from '@rawcmd/typewriters';

const typewriter = rowTypewriter([
  { index: 0, width: 20 },
  { index: 1, width: 60 },
], {
  separatorSymbol: ' | ',
});
const text = typewriter([
  'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
  'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
]);

summaryTypewriter(options): Function(command)

Returns a function which builds a string representing command summary text.

textTypewriter(options): Function(data)

Applyes styles to the provided string.

import { TextAlign, TextColor, textTypewriter } from '@rawcmd/typewriters';

const typewriter = textTypewriter({
  align: TextAlign.RIGHT,
  bold: true,
  color: TextColor.MAGENTA
});
const text = typewriter('Hello World!');

titleTypewriter: Function(text)

Returns a function which builds a string representing section title.

usageTypewriter: Function(command)

Returns a function which builds a string showing how the command should be used with examples.

Package	Description	Version
@rawcmd/core	Core framework logic.
@rawcmd/text	Text manipulation methods.
@rawcmd/typewriters	Collection of typewriters.
@rawcmd/utils	Helper functions.

See CONTRIBUTING.md for how to help out.

See LICENSE for details.