{"id":17314,"library":"oclif","title":"oclif CLI Framework","description":"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.","status":"active","version":"4.23.0","language":"javascript","source_language":"en","source_url":"https://github.com/oclif/oclif","tags":["javascript","oclif","cli","typescript"],"install":[{"cmd":"npm install oclif","lang":"bash","label":"npm"},{"cmd":"yarn add oclif","lang":"bash","label":"yarn"},{"cmd":"pnpm add oclif","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"oclif CLIs require Node.js version 18 or higher to run, as specified in the 'engines' field.","package":"node","optional":false}],"imports":[{"note":"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.","wrong":"const { Command } = require('oclif');","symbol":"Command","correct":"import { Command, Args, Flags } from '@oclif/core';"},{"note":"`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`.","wrong":"import { run } from 'oclif';","symbol":"run","correct":"import { run } from '@oclif/core';"},{"note":"`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.","wrong":"import { CliUx } from '@oclif/parser';","symbol":"CliUx","correct":"import { CliUx } from '@oclif/core';"}],"quickstart":{"code":"import { Command, Args, Flags } from '@oclif/core';\n\nexport default class Hello extends Command {\n  static description = 'Say hello to a person';\n\n  static examples = [\n    '<%= config.bin %> <%= command.id %> world --from oclif',\n  ];\n\n  static flags = {\n    from: Flags.string({ char: 'f', description: 'Who is saying hello', required: true }),\n  };\n\n  static args = {\n    person: Args.string({ description: 'Person to say hello to', required: true }),\n  };\n\n  public async run(): Promise<void> {\n    const { args, flags } = await this.parse(Hello);\n\n    this.log(`Hello from ${flags.from}, ${args.person}!`);\n  }\n}\n\n// To generate a new CLI project, run:\n// npx oclif generate mynewcli\n// cd mynewcli\n// ./bin/run.js hello world --from me","lang":"typescript","description":"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."},"warnings":[{"fix":"Replace calls to `oclif multi`, `oclif plugin`, or `oclif single` with `oclif generate <cli-name>`.","message":"The `oclif multi`, `oclif plugin`, and `oclif single` commands have been removed. Use `oclif generate` instead to create new oclif CLIs.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update scripts and documentation to use the new command names: `oclif generate:hook` and `oclif generate:command`.","message":"The commands `oclif hook` and `oclif command` have been renamed. They are now `oclif generate:hook` and `oclif generate:command` respectively.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"oclif CLIs require Node.js version 18 or higher. Running with older Node versions will result in errors or unexpected behavior.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import oclif core components using CommonJS `require()` syntax in an ESM context, or vice-versa.","error":"TypeError: Command is not a constructor"},{"fix":"Update your Node.js installation to version 18 or greater. Use `nvm install 18` and `nvm use 18` or similar version management tools.","cause":"Attempting to run an oclif CLI with an unsupported Node.js version.","error":"Error: The 'oclif' CLI is designed for Node.js version 18 or higher."},{"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.","cause":"Using a deprecated `oclif` command (`multi`, `plugin`, `single`, `hook`, `command`) from an older oclif v1 API on a v2+ installation.","error":"Unknown command \"multi\""}],"ecosystem":"npm","meta_description":null}