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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
vorpal
✓ const vorpal = require('vorpal')();
✗ import vorpal from 'vorpal';
// OR
import { vorpal } from '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
✓ vorpal.command('foo', 'description').action(function(args, callback) { /* ... */ });
✗ const command = vorpal.command('foo');
command.action(...);
Commands are typically chained directly off the `vorpal` instance. While technically possible to separate, chaining is the idiomatic way.
vorpal.show()
✓ vorpal.show();
✗ vorpal.delimiter('myapp$');
// ... more code ...
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.
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();
vorpal --version
Debug
Known issues
breakingThe 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.fixEvaluate the project's long-term viability for new applications. Consider contributing as a maintainer or exploring alternative, actively maintained CLI frameworks for critical projects.
affects: >=1.12.0
breakingVorpal'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.fixThoroughly 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.
affects: >=1.0.0 (when run on modern Node.js)
gotchaVorpal 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.fixIf 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).
affects: >=1.0.0
gotchaThe `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.fixAlways 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`.
affects: >=1.0.0
Errors
Common errors & fixes
require is not defined in ES module scope
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`).
fixRename 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
Invoking `require('vorpal')` directly without the `()` to instantiate the Vorpal object.
fixEnsure you call the required module as a function: `const vorpal = require('vorpal')();` The CLI prompt does not return or hangs after command execution.
The `callback()` function passed to the command's `action` method was not invoked.
fixEnsure `callback()` is called at the end of your command's `action` function, signaling completion to Vorpal.
Audit
Dependencies
commander.jsrequiredFramework inspiration and basis for command creation API.
inquirer.jsrequiredProvides the interactive prompt functionality for the CLI environment.