What is oclif?
oclif is a framework for building command-line interfaces (CLIs) in Node.js. It provides a robust set of tools and conventions for creating and managing CLI applications, including support for plugins, argument parsing, and command scaffolding.
What are oclif's main functionalities?
Command Creation
This feature allows you to create new commands easily. The example demonstrates a simple 'Hello, world!' command.
const { Command } = require('@oclif/core');
class HelloWorldCommand extends Command {
async run() {
this.log('Hello, world!');
}
}
HelloWorldCommand.run();
Argument Parsing
This feature provides built-in support for parsing command-line arguments and flags. The example shows a command that greets a user by name.
const { Command, flags } = require('@oclif/core');
class GreetCommand extends Command {
static flags = {
name: flags.string({ char: 'n', description: 'name to print' })
};
async run() {
const { flags } = this.parse(GreetCommand);
this.log(`Hello, ${flags.name || 'world'}!`);
}
}
GreetCommand.run();
Plugins
This feature allows you to extend your CLI with plugins. The example demonstrates loading plugins within a command.
const { Command } = require('@oclif/core');
const { Plugins } = require('@oclif/plugin-plugins');
class MyCommand extends Command {
async run() {
const plugins = new Plugins(this.config);
await plugins.load();
this.log('Plugins loaded');
}
}
MyCommand.run();
Other packages similar to oclif
commander
Commander is a popular library for building command-line interfaces in Node.js. It provides a simple and flexible API for defining commands, options, and arguments. Compared to oclif, Commander is more lightweight and less opinionated, making it a good choice for simpler CLI applications.
yargs
Yargs is another widely-used library for building CLI applications in Node.js. It offers powerful argument parsing capabilities and a rich set of features for handling complex command-line interfaces. Yargs is more feature-rich than Commander but still less structured than oclif, which provides a more comprehensive framework for CLI development.
vorpal
Vorpal is a framework for building interactive command-line applications in Node.js. It supports features like command history, tab completion, and interactive prompts. Vorpal is more focused on creating interactive CLIs, whereas oclif is designed for building both simple and complex command-line tools.
oclif: Open CLI Framework
Create your own CLI
Description
This is a framework for building CLIs in Node.js. This framework was built out of the Heroku CLI but generalized to build any custom CLI. It's designed both for simple CLIs that can be just a single file with a few flag options, or for very complex CLIs that have many commands (like git or heroku).
Most CLI tools for Node are simple flag parsers but oclif is much more than that—though without the overhead of making simple CLIs quick to write with minimal boilerplate.
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 easily use the CLI in ways they expect, but without comprisiming strictness guarantees to the developer.
- CLI Generator - Run a single command to scaffold out a fully functional CLI and get started quickly. See Usage below.
- 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 multi-command CLI example - Advanced plugin capabilility - 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 below.
- 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 (or not) - Everything in the core of oclif is written in TypeScript and the generator can build fully configured TypeScript CLIs or just plain JavaScript CLIs. By virtue of static properties in TypeScript the syntax is a bit cleaner in TypeScript—but everything will work no matter which language you choose. If you use plugins support, the CLI will automatically use
ts-node
to run the plugins making it easy and fast to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI. - Coming soon: Autocomplete - Automatically include autocomplete for your CLI. This includes not just command names and flag names, but flag values as well. For example, it's easy to configure the Heroku CLI to have completions for Heroku app names:
- Coming soon: man pages - In addition to in-CLI help through
--help
and the README markdown help generation, the CLI can also automatically create man pages for all of its commands.
$ heroku info --app=<tab><tab> # will complete with all the Heroku apps a user has in their account
Install
with yarn:
$ yarn global add oclif
or with npm:
$ npm install -g oclif
Usage
$ oclif COMMAND
running command...
$ oclif (-v|--version|version)
oclif/1.2.5 (linux-x64) node-v9.5.0
$ oclif --help [COMMAND]
USAGE
$ oclif COMMAND [OPTIONS]
...
Commands
command NAME [OPTIONS]
add a command to an existing CLI or plugin
USAGE
$ oclif command NAME
ARGUMENTS
NAME name of command
OPTIONS
--defaults use defaults for every setting
--force overwrite existing files
See code: src/commands/command.ts
help [COMMAND] [OPTIONS]
display help for oclif
USAGE
$ oclif help [COMMAND]
ARGUMENTS
COMMAND command to show help for
OPTIONS
--all see all commands in CLI
See code: @oclif/plugin-help
multi [PATH] [OPTIONS]
generate a new multi-command CLI
USAGE
$ oclif multi [PATH]
OPTIONS
--defaults use defaults for every setting
--force overwrite existing files
--options=options (typescript|semantic-release|mocha)
See code: src/commands/multi.ts
plugin [PATH] [OPTIONS]
create a new CLI plugin
USAGE
$ oclif plugin [PATH]
OPTIONS
--defaults use defaults for every setting
--force overwrite existing files
--options=options (typescript|semantic-release|mocha)
See code: src/commands/plugin.ts
single [PATH] [OPTIONS]
generate a new single-command CLI
USAGE
$ oclif single [PATH]
OPTIONS
--defaults use defaults for every setting
--force overwrite existing files
--options=options (typescript|semantic-release|mocha)
See code: src/commands/single.ts
Examples
Plugins
Building your own plugin
Writing code for plugins is essentially the same as writing within a CLI. They can export 3 different types: commands, hooks, and other plugins.
Run npx oclif plugin mynewplugin
to create a plugin in a new directory. This will come with a sample command called hello
.