@oclif/command

What is @oclif/command?

@oclif/command is a framework for building command-line interface (CLI) applications. It provides a robust set of tools and conventions for creating, organizing, and managing CLI commands, arguments, and options.

What are @oclif/command's main functionalities?

Creating a Basic Command

This feature allows you to create a basic command that prints 'Hello, world!' to the console. The Command class is extended to define the behavior of the command.

const { Command } = require('@oclif/command');

class HelloWorldCommand extends Command {
  async run() {
    this.log('Hello, world!');
  }
}

HelloWorldCommand.run();

Adding Arguments and Flags

This feature allows you to add arguments and flags to your command. In this example, the command takes an optional 'name' argument and a 'greeting' flag to customize the output.

const { Command, flags } = require('@oclif/command');

class GreetCommand extends Command {
  async run() {
    const { args, flags } = this.parse(GreetCommand);
    const name = args.name || 'world';
    const greeting = flags.greeting || 'Hello';
    this.log(`${greeting}, ${name}!`);
  }
}

GreetCommand.args = [
  { name: 'name' }
];

GreetCommand.flags = {
  greeting: flags.string({ char: 'g', description: 'greeting to use' })
};

GreetCommand.run();

Command Aliases

This feature allows you to define aliases for your commands. In this example, the 'HelloWorldCommand' can be invoked using 'hw' or 'hello' as aliases.

const { Command } = require('@oclif/command');

class HelloWorldCommand extends Command {
  async run() {
    this.log('Hello, world!');
  }
}

HelloWorldCommand.aliases = ['hw', 'hello'];

HelloWorldCommand.run();

Other packages similar to @oclif/command

commander

Commander is a popular library for building command-line interfaces. It provides a simple and flexible API for defining commands, arguments, and options. Compared to @oclif/command, Commander is more lightweight and has fewer built-in features, but it is easier to get started with for simple CLI applications.

yargs

Yargs is another library for building command-line interfaces. It focuses on providing a powerful and user-friendly API for parsing arguments and generating help messages. Yargs offers more advanced argument parsing capabilities compared to @oclif/command, but it may require more configuration for complex CLI applications.

caporal

Caporal is a full-featured framework for building command-line applications. It provides a rich set of features for defining commands, arguments, options, and subcommands. Caporal is similar to @oclif/command in terms of functionality, but it has a different API and design philosophy.

README

@oclif/command

oclif base command

This is about half of the main codebase for oclif. The other half lives in @oclif/config. This can be used directly, but it probably makes more sense to build your CLI with the generator.

Usage

Without the generator, you can create a simple CLI like this:

TypeScript

#!/usr/bin/env ts-node

import * as fs from 'fs'
import {Command, flags} from '@oclif/command'

class LS extends Command {
  static flags = {
    version: flags.version(),
    help: flags.help(),
    // run with --dir= or -d=
    dir: flags.string({
      char: 'd',
      default: process.cwd(),
    }),
  }

  async run() {
    const {flags} = this.parse(LS)
    let files = fs.readdirSync(flags.dir)
    for (let f of files) {
      this.log(f)
    }
  }
}

LS.run()
.catch(require('@oclif/errors/handle'))

JavaScript

#!/usr/bin/env node

const fs = require('fs')
const {Command, flags} = require('@oclif/command')

class LS extends Command {
  async run() {
    const {flags} = this.parse(LS)
    let files = fs.readdirSync(flags.dir)
    for (let f of files) {
      this.log(f)
    }
  }
}

LS.flags = {
  version: flags.version(),
  help: flags.help(),
  // run with --dir= or -d=
  dir: flags.string({
    char: 'd',
    default: process.cwd(),
  }),
}

LS.run()
.catch(require('@oclif/errors/handle'))

Then run either of these with:

$ ./myscript
...files in current dir...
$ ./myscript --dir foobar
...files in ./foobar...
$ ./myscript --version
myscript/0.0.0 darwin-x64 node-v9.5.0
$ ./myscript --help
USAGE
  $ @oclif/command

OPTIONS
  -d, --dir=dir  [default: /Users/jdickey/src/github.com/oclif/command]
  --help         show CLI help
  --version      show CLI version

See the generator for all the options you can pass to the command.