oclif CLI Framework

4.23.0 · active · verified Wed Apr 22

oclif (Open CLI Framework) is a robust and extensible framework for building command-line interface (CLI) applications using Node.js and TypeScript. It provides a structured approach to CLI development, handling common tasks like command parsing, argument and flag definition, help generation, and plugin management. Currently in its 4.x major version, oclif receives frequent maintenance updates, primarily bug fixes and dependency bumps, indicating active development. Key differentiators include its extensibility via plugins, comprehensive documentation, and its adoption by major projects such as the Salesforce CLI and Heroku CLI. It's designed to support both single-command CLIs and multi-command CLIs with ease, abstracting away much of the boilerplate associated with CLI creation.

Common errors

```
TypeError: Command is not a constructor
```
cause Attempting to import oclif core components using CommonJS `require()` syntax in an ESM context, or vice-versa.

fix Ensure you are using `import { Command } from '@oclif/core';` for ESM modules. If strictly in CommonJS, consider transpiling or updating your project to ESM. Most modern oclif usage expects ESM.
```
Error: The 'oclif' CLI is designed for Node.js version 18 or higher.
```
cause Attempting to run an oclif CLI with an unsupported Node.js version.

fix Update your Node.js installation to version 18 or greater. Use `nvm install 18` and `nvm use 18` or similar version management tools.
```
Unknown command "multi"
```
cause Using a deprecated `oclif` command (`multi`, `plugin`, `single`, `hook`, `command`) from an older oclif v1 API on a v2+ installation.

fix Consult the migration guide from v1 to v2. Use `oclif generate` for creating new CLIs/plugins, and `oclif generate:hook` or `oclif generate:command` for generating specific components.

Warnings

breaking The `oclif multi`, `oclif plugin`, and `oclif single` commands have been removed. Use `oclif generate` instead to create new oclif CLIs.
Fix: Replace calls to `oclif multi`, `oclif plugin`, or `oclif single` with `oclif generate <cli-name>`.
breaking The commands `oclif hook` and `oclif command` have been renamed. They are now `oclif generate:hook` and `oclif generate:command` respectively.
Fix: Update scripts and documentation to use the new command names: `oclif generate:hook` and `oclif generate:command`.
gotcha oclif CLIs require Node.js version 18 or higher. Running with older Node versions will result in errors or unexpected behavior.
Fix: Ensure your development and production environments use Node.js 18 or a newer LTS version. Use a tool like `nvm` to manage Node versions.
gotcha oclif and its core library (`@oclif/core`) are designed for ES Modules (ESM). While older versions might have had some CommonJS compatibility, recent versions and best practices lean heavily into ESM.
Fix: Always use `import` statements for oclif components. Ensure your `package.json` specifies `"type": "module"` if not already set, or use `.mjs` file extensions for ESM files.

Install

npm install oclif npm
yarn add oclif yarn
pnpm add oclif pnpm

Imports

Command
wrong:
```
const { Command } = require('oclif');
```
correct:
```
import { Command, Args, Flags } from '@oclif/core';
```
Core CLI development components like `Command`, `Args`, and `Flags` are imported from `@oclif/core`, not directly from the `oclif` package, which is the CLI generation tool itself. oclif is primarily ESM-only in modern versions.
run
wrong:
```
import { run } from 'oclif';
```
correct:
```
import { run } from '@oclif/core';
```
`run` is the entry point function for programmatically executing an oclif CLI application, typically used in `bin/run.js` or similar entry files. It's part of `@oclif/core`.
CliUx
wrong:
```
import { CliUx } from '@oclif/parser';
```
correct:
```
import { CliUx } from '@oclif/core';
```
`CliUx` provides utility functions for user interaction, such as displaying spinners, prompts, or formatted output. It is imported from `@oclif/core` and offers a unified way to handle user experience components in CLIs.

Quickstart

This quickstart demonstrates how to define a basic 'hello' command with arguments and flags within an oclif CLI, and how to create a new oclif project.

import { Command, Args, Flags } from '@oclif/core';

export default class Hello extends Command {
  static description = 'Say hello to a person';

  static examples = [
    '<%= config.bin %> <%= command.id %> world --from oclif',
  ];

  static flags = {
    from: Flags.string({ char: 'f', description: 'Who is saying hello', required: true }),
  };

  static args = {
    person: Args.string({ description: 'Person to say hello to', required: true }),
  };

  public async run(): Promise<void> {
    const { args, flags } = await this.parse(Hello);

    this.log(`Hello from ${flags.from}, ${args.person}!`);
  }
}

// To generate a new CLI project, run:
// npx oclif generate mynewcli
// cd mynewcli
// ./bin/run.js hello world --from me

view raw JSON →