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: Node.JS Open CLI Framework
π 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 single-file CLIs with a few flag options, 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 35 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 Usage below.
- 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 multi-command 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 from V1
If you have been using version 1 of the oclif
CLI there are some important differences to note when using the latest version.
Breaking Changes
oclif multi
, oclif plugin
, and oclif single
have all been removed in favor of oclif generate
, which generates an oclif based CLI using the hello-world example repo.
- The reason is that there's not enough of a meaningful difference between a "multi command cli", a "single command cli", and a "plugin" to justify the maintenance cost. The generated CLI can be easily used for any of those use cases.
oclif hook
is now oclif generate:hook
oclif command
is now oclif generate:command
New Commands
Version 2 now includes all the commands from the oclif-dev
CLI. This means that you can now use a single CLI for all your oclif needs. These commands include:
oclif manifest
oclif pack
oclif pack:deb
oclif pack:macos
oclif pack:win
oclif upload
(formerly known as oclif-dev publish
)oclif upload:deb
(formerly known as oclif-dev publish:deb
)oclif upload:macos
(formerly known as oclif-dev publish:macos
)oclif upload:win
(formerly known as oclif-dev publish:win
)oclif readme
π Usage
Creating a CLI:
$ npx oclif generate mynewcli
? npm package name (mynewcli): mynewcli
$ cd mynewcli
$ ./bin/run.js --version
mynewcli/0.0.0 darwin-x64 node-v9.5.0
$ ./bin/run.js --help
USAGE
$ mynewcli [COMMAND]
COMMANDS
hello
help display help for mynewcli
$ ./bin/run.js hello world
hello world! (./src/commands/hello/world.ts)
π Examples
π¨ Commands
Command Topics
π Related Repositories
π¦ Learn More
π£ Feedback
If you have any suggestions or want to let us know what you think of oclif, send us a message at alm-cli@salesforce.com