oclif

library4.23.0jsnpmunverified

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.

devops

npm install oclif

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OCLIF

oclif

devopsjavascriptv4.23.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Command

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

✗ const { Command } = require('oclif');

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

✓ import { run } from '@oclif/core';

✗ import { run } from 'oclif';

`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

✓ import { CliUx } from '@oclif/core';

✗ import { CliUx } from '@oclif/parser';

`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.

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

Debug

Known issues

breakingThe `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>`.

affects: >=2.0.0

breakingThe 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`.

affects: >=2.0.0

gotchaoclif 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.

affects: >=4.0.0

gotchaoclif 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.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: Command is not a constructor

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.

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"

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.

Upgrade

Version history

4.23.0latest on npm

Audit

Dependencies

noderequiredoclif CLIs require Node.js version 18 or higher to run, as specified in the 'engines' field.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/oclif/oclif ↗

packagehttps://www.npmjs.com/package/oclif ↗

homepagehttps://oclif.io ↗