CLI Commands

Writing new commands

Commands are classes which extend the base Command class (see command.js).

The only required override is the handle() method, which defines the logic for the command:

const Command = require('./command');

module.exports = class REPL extends Command {
    async handle(argv = {}) {
        // this is where your logic is implemented
    }
};

Arguments

Optionally, you can override the setup() method, where you can define any command-line arguments and help text etc:

    setup() {
        this.help('A brief explanation of what your command does, shown when the --help flag is used');
        // arguments are passed to sywac - see https://sywac.io/docs/
        this.argument('--color', {type: 'string', defaultValue: 'yellow'});
    }

Arguments specified in setup() are accessed from the argv object passed to the handle() method:

async handle(argv = {}) {
    this.log(`Your color is ${argv.color}`);
}

Output

You can write console output using a number of helper methods:

this.log('Writes a line to the console');

Available helpers are log, ok, info, error, fatal, warn, and debug.

Interactive input

Confirm an action with:

const confirm = await this.confirm('Are you sure you want to continue?');
if (!confirm) {
    // ...
}

Ask for user input with:

const fruit = await this.ask('Favorite fruit?');
this.info(`You answered: ${fruit}`);

Get masked input with:

const password = await this.secret('Password:');
this.log(`Your password is: ${password}`);

Progress bars

You can show a progress bar to e.g. display progress through a long-running task.

this.progressBar() returns an instance of a cli-progress progress bar. You can add a status to the output by calling .update({status: 'Your status message'}), and the progress bar can be advanced by .increment():

const progressBar = this.progressBar(listOfTasks.length);
for (const task in listOfTasks) {
    progressBar.update({status: `Running ${task.name}`});
    await task.run();
    progressBar.increment();
}

Registering commands

New commands need to be registered in ghost.js before they can be called.

Commands are called by passing them to command.run() either as a class definition, or as the name of the file to be required in the core/cli directory.

command.run() is a static method on the Command class that handles instantiating the command, resolving arguments, and calling the handle method. You can instantiate and call a command outside of this structure, but you'll need to resolve/provide the arguments (argv object) manually.