{"id":12390,"library":"vorpal","title":"Vorpal CLI Framework","description":"Vorpal is a framework designed for building interactive command-line interface (CLI) applications in Node.js, positioning itself as an early pioneer in creating immersive CLI environments. It offers a comprehensive API for defining commands, handling arguments and options, enabling piped commands, providing persistent history, built-in help, and tab-completion. The framework is built upon and inspired by `commander.js` for its command structure and `inquirer.js` for interactive prompting, creating an isolated, shell-like experience. The current stable version, 1.12.0, was released some time ago, and the project is explicitly in an 'OPEN Open Source' state, actively seeking new maintainers, indicating a minimal or inactive release cadence from the original author. Its key differentiator is providing a full interactive shell within Node.js, facilitating complex, rich CLI applications through a simple API and extensibility.","status":"maintenance","version":"1.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/dthree/vorpal","tags":["javascript","api","cli","repl","shell","immersive","framework","app","application"],"install":[{"cmd":"npm install vorpal","lang":"bash","label":"npm"},{"cmd":"yarn add vorpal","lang":"bash","label":"yarn"},{"cmd":"pnpm add vorpal","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Framework inspiration and basis for command creation API.","package":"commander.js","optional":false},{"reason":"Provides the interactive prompt functionality for the CLI environment.","package":"inquirer.js","optional":false}],"imports":[{"note":"Vorpal v1.x is primarily a CommonJS module and expects to be initialized immediately after requiring. Direct ES Module imports are not supported.","wrong":"import vorpal from 'vorpal';\n// OR\nimport { vorpal } from 'vorpal';","symbol":"vorpal","correct":"const vorpal = require('vorpal')();"},{"note":"Commands are typically chained directly off the `vorpal` instance. While technically possible to separate, chaining is the idiomatic way.","wrong":"const command = vorpal.command('foo');\ncommand.action(...);","symbol":"Command instance","correct":"vorpal.command('foo', 'description').action(function(args, callback) { /* ... */ });"},{"note":"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.","wrong":"vorpal.delimiter('myapp$');\n// ... more code ...\nvorpal.show();","symbol":"vorpal.show()","correct":"vorpal.show();"}],"quickstart":{"code":"const vorpal = require('vorpal')();\n\nvorpal\n  .command('greet <name>', 'Greets the given name.')\n  .option('-p, --polite', 'Use a polite greeting.')\n  .action(function(args, callback) {\n    const greeting = args.options.polite ? 'Hello there, ' : 'Hi, ';\n    this.log(`${greeting}${args.name}!`)\n    callback();\n  });\n\nvorpal\n  .command('add <numbers...>', 'Adds a list of numbers.')\n  .action(function(args, callback) {\n    const sum = args.numbers.reduce((acc, num) => acc + parseFloat(num), 0);\n    this.log(`The sum is: ${sum}`);\n    callback();\n  });\n\nvorpal\n  .delimiter('mycli$')\n  .show();","lang":"javascript","description":"This quickstart demonstrates defining two commands: `greet` with an argument and an optional flag, and `add` with variadic arguments, then initializes the interactive CLI."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.12.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0 (when run on modern Node.js)"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","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`).","error":"require is not defined in ES module scope"},{"fix":"Ensure you call the required module as a function: `const vorpal = require('vorpal')();`","cause":"Invoking `require('vorpal')` directly without the `()` to instantiate the Vorpal object.","error":"TypeError: vorpal is not a function"},{"fix":"Ensure `callback()` is called at the end of your command's `action` function, signaling completion to Vorpal.","cause":"The `callback()` function passed to the command's `action` method was not invoked.","error":"The CLI prompt does not return or hangs after command execution."}],"ecosystem":"npm"}