Vorpal CLI Framework

Common errors

• require is not defined in ES module scope

  cause Attempting to use `require('vorpal')` in a file that Node.js interprets as an ES Module (e.g., a `.mjs` file or when `type: 'module'` is set in `package.json`).
  fix Rename your file to `.cjs` or set `type: 'commonjs'` in your `package.json` for that file/directory. Alternatively, if your setup supports it, consider a dynamic import: `const vorpal = (await import('vorpal')).default();` (though direct instantiation might differ).

• TypeError: vorpal is not a function

  cause Invoking `require('vorpal')` directly without the `()` to instantiate the Vorpal object.
  fix Ensure you call the required module as a function: `const vorpal = require('vorpal')();`

• The CLI prompt does not return or hangs after command execution.

  cause The `callback()` function passed to the command's `action` method was not invoked.
  fix Ensure `callback()` is called at the end of your command's `action` function, signaling completion to Vorpal.

Warnings

• breaking The Vorpal project is currently in 'OPEN Open Source' status, with the original author unable to actively maintain it and seeking new volunteers. This means bug fixes, security patches, and new features are highly unlikely unless new maintainers step forward.
  Fix: Evaluate the project's long-term viability for new applications. Consider contributing as a maintainer or exploring alternative, actively maintained CLI frameworks for critical projects.
• breaking Vorpal's declared `engines` (`node >= 0.10.0`, `iojs >= 1.0.0`) are for extremely old Node.js versions. Running Vorpal on modern Node.js environments (e.g., Node.js 16+ or 18+) may lead to compatibility issues, deprecated API warnings, or runtime errors due to breaking changes in Node.js core or its dependencies over time.
  Fix: Thoroughly test Vorpal applications against your target Node.js version. Be prepared to address runtime errors or compatibility layers. Downgrading Node.js is generally not recommended for security reasons.
• gotcha Vorpal v1.x is a CommonJS module. Attempting to use `import` statements directly in an ES Module project without proper CommonJS interoperability configuration will lead to errors.
  Fix: If integrating into an ESM project, use dynamic `import()` or ensure your build setup correctly handles CommonJS module loading (e.g., Babel, Webpack, or native Node.js ESM/CJS interop features).
• gotcha The `action` callback for commands requires `callback()` to be called at the end of the asynchronous operation, otherwise the Vorpal prompt will not return, appearing to hang.
  Fix: Always ensure the `callback()` function is invoked within the `action` method, even for synchronous operations, to release the prompt. For Promises, wrap them in an `async` function and call `callback()` after `await`.

Install

• npm install vorpal npm
• yarn add vorpal yarn
• pnpm add vorpal pnpm

Imports

• vorpal
  wrong:

  import vorpal from 'vorpal';
  // OR
  import { vorpal } from 'vorpal';

  correct:

  const vorpal = require('vorpal')();

  Vorpal v1.x is primarily a CommonJS module and expects to be initialized immediately after requiring. Direct ES Module imports are not supported.
• Command instance
  wrong:

  const command = vorpal.command('foo');
  command.action(...);

  correct:

  vorpal.command('foo', 'description').action(function(args, callback) { /* ... */ });

  Commands are typically chained directly off the `vorpal` instance. While technically possible to separate, chaining is the idiomatic way.
• vorpal.show()
  wrong:

  vorpal.delimiter('myapp$');
  // ... more code ...
  vorpal.show();

  correct:

  vorpal.show();

  It is crucial to call `vorpal.show()` to start the interactive prompt after defining commands and settings. Omission will result in the app exiting without showing the CLI.

Quickstart

This quickstart demonstrates defining two commands: `greet` with an argument and an optional flag, and `add` with variadic arguments, then initializes the interactive CLI.

const vorpal = require('vorpal')();

vorpal
  .command('greet <name>', 'Greets the given name.')
  .option('-p, --polite', 'Use a polite greeting.')
  .action(function(args, callback) {
    const greeting = args.options.polite ? 'Hello there, ' : 'Hi, ';
    this.log(`${greeting}${args.name}!`)
    callback();
  });

vorpal
  .command('add <numbers...>', 'Adds a list of numbers.')
  .action(function(args, callback) {
    const sum = args.numbers.reduce((acc, num) => acc + parseFloat(num), 0);
    this.log(`The sum is: ${sum}`);
    callback();
  });

vorpal
  .delimiter('mycli$')
  .show();