@oclif/core

What is @oclif/core?

The @oclif/core npm package is a framework for building command-line interfaces (CLIs) in Node.js. It provides a powerful set of tools to develop sophisticated CLIs with features such as argument parsing, command structure, and plugin support. This package is part of the Open CLI Framework (OCLIF) developed by Heroku.

What are @oclif/core's main functionalities?

Command Creation

This feature allows developers to create custom commands for their CLI. The code sample demonstrates how to define a simple command that accepts a name as a flag and prints a greeting message.

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

class MyCommand extends Command {
  async run() {
    const {flags} = await this.parse(MyCommand);
    console.log(`Hello, ${flags.name}!`);
  }
}

MyCommand.description = 'Describe the command here';

MyCommand.flags = {
  name: flags.string({char: 'n', description: 'name to print'}),
};

module.exports = MyCommand;

Argument Parsing

This feature simplifies the process of parsing arguments passed to commands. The code sample shows how to create a command that echoes a message passed as an argument.

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

class EchoCommand extends Command {
  async run() {
    const {args} = await this.parse(EchoCommand);
    console.log(`Echoing: ${args.message}`);
  }
}

EchoCommand.args = [{name: 'message'}];

module.exports = EchoCommand;

Plugin Support

OCLIF supports plugins to extend the functionality of your CLI. This code sample demonstrates how to define a simple plugin that includes a custom command.

const {Command, Plugin} = require('@oclif/core');

class MyPlugin extends Plugin {
  constructor(root, config) {
    super(root, config);
    this.name = 'my-plugin';
  }

  commands = [require('./commands/my-command')];
}

module.exports = MyPlugin;

Other packages similar to @oclif/core

commander

Commander is a lightweight, expressive, and powerful command-line framework for Node.js. It provides a simpler API compared to @oclif/core but lacks some of the advanced features such as plugin support and automatic help generation.

yargs

Yargs helps you build interactive command-line tools, by parsing arguments and generating an elegant user interface. It's more focused on parsing arguments and providing a fluent API, whereas @oclif/core offers a more structured approach to building CLIs with support for plugins and multi-command CLIs.

vorpal

Vorpal is a framework for building immersive CLI applications in Node. It offers a similar command-based structure to @oclif/core but with a focus on interactive command-line interfaces. Vorpal is less actively maintained compared to @oclif/core.

README

oclif: Node.JS Open CLI Framework

🗒 Description

This is a framework for building CLIs in Node.js. This framework was built out of the Salesforce CLI but generalized to build any custom CLI. It's designed both for single-file CLIs with a few flag options (like cat or ls), or for very complex CLIs that have subcommands (like git or heroku).

See the docs for more information.

🚀 Getting Started Tutorial

The Getting Started tutorial is a step-by-step guide to introduce you to oclif. If you have not developed anything in a command line before, this tutorial is a great place to get started.

✨ Features

• Flag/Argument parsing - No CLI framework would be complete without a flag parser. We've built a custom one from years of experimentation that we feel consistently handles user input flexible enough for the user to be able to use the CLI in ways they expect, but without compromising strictness guarantees to the developer.
• Super Speed - The overhead for running an oclif CLI command is almost nothing. It requires very few dependencies (only 28 dependencies in a minimal setup—including all transitive dependencies). Also, only the command to be executed will be required with node. So large CLIs with many commands will load equally as fast as a small one with a single command.
• CLI Generator - Run a single command to scaffold out a fully functional CLI and get started quickly. See Getting Started Tutorial.
• Testing Helpers - We've put a lot of work into making commands easier to test and mock out stdout/stderr. The generator will automatically create scaffolded tests.
• Auto-documentation - By default you can pass --help to the CLI to get help such as flag options and argument information. This information is also automatically placed in the README whenever the npm package of the CLI is published. See the hello-world CLI example
• Plugins - Using plugins, users of the CLI can extend it with new functionality, a CLI can be split into modular components, and functionality can be shared amongst multiple CLIs. See Building your own plugin.
• Hooks - Use lifecycle hooks to run functionality any time a CLI starts, or on custom triggers. Use this whenever custom functionality needs to be shared between various components of the CLI.
• TypeScript - Everything in the core of oclif is written in TypeScript and the generator will build fully configured TypeScript CLIs. If you use plugins support, the CLI will automatically use ts-node to run the plugins enabling you to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI.
• Auto-updating Installers - oclif can package your CLI into different installers that will not require the user to already have node installed on the machine. These can be made auto-updatable by using plugin-update.
• Everything is Customizable - Pretty much anything can be swapped out and replaced inside oclif if needed—including the arg/flag parser.
• Autocomplete - Automatically include autocomplete for your CLI. This includes not only command names and flag names, but flag values as well. For example, it's possible to configure the Heroku CLI to have completions for Heroku app names:

$ heroku info --app=<tab><tab> # will complete with all the Heroku apps a user has in their account

📌 Requirements

Currently, Node 18+ is supported. We support the LTS versions of Node. You can add the node package to your CLI to ensure users are running a specific version of Node.

📌 Migrating

See the v3 migration guide for an overview of breaking changes that occurred between v2 and v3.

See the v2 migration guide for an overview of breaking changes that occurred between v1 and v2.

Migrating from @oclif/config and @oclif/command? See the v1 migration guide.

📌 Documentation

The official oclif website, oclif.io, contains all the documentation you need for developing a CLI with oclif.

If there's anything you'd like to see in the documentation, please submit an issue on the oclif.github.io repo.

🚀 Standalone Usage

We strongly encourage you generate an oclif CLI using the oclif cli. The generator will generate an npm package with @oclif/core as a dependency.

You can, however, use @oclif/core in a standalone script like this:

#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning

import * as fs from 'fs'
import {Command, Flags, flush, handle} from '@oclif/core'

class LS extends Command {
  static description = 'List the files in a directory.'
  static flags = {
    version: Flags.version(),
    help: Flags.help(),
    dir: Flags.string({
      char: 'd',
      default: process.cwd(),
    }),
  }

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

LS.run().then(
  async () => {
    await flush()
  },
  async (err) => {
    await handle(err)
  },
)

Then run it like this:

$ ts-node myscript.ts
...files in current dir...

You can also use oclif's Parser separately:

// index.js
import {Args, Flags, Parser} from '@oclif/core'

const {args, flags} = await Parser.parse(process.argv.slice(2), {
  args: {
    name: Args.string({required: true}),
  },
  flags: {
    from: Flags.string({char: 'f', default: 'oclif'}),
  },
})

console.log(`hello ${args.name} from ${flags.form}`)

$ node index.js world --from oclif

hello world from oclif

🚀 Contributing

See the contributing guide.

Changelog

4.0.28 (2024-10-11)

Bug Fixes

• remove circular references when colorizing json (de9ed4e)