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.
commist
✓ const commist = require('commist')
✗ import commist from 'commist'
Commist is primarily designed for CommonJS. It exports a factory function that returns the program instance. For ESM, you might need `import * as commistModule from 'commist'; const commist = commistModule.default || commistModule;` but direct CJS `require` is the canonical usage.
program.register
✓ program.register('command-name', function(args) { /* ... */ })
✗ program.registerAsync('command-name', async function(args) { /* ... */ })
Use `register` for both synchronous and asynchronous command handlers. The choice between `parse` and `parseAsync` determines how they are invoked.
program.parse
✓ const result = program.parse(process.argv.splice(2))
✗ await program.parse(process.argv.splice(2))
Use `parse` for synchronous command execution. If any registered command is `async`, it will return a Promise which will not be awaited. For proper async handling, use `parseAsync`.
program.parseAsync
✓ const result = await program.parseAsync(process.argv.splice(2))
✗ const result = program.parseAsync(process.argv.splice(2))
`parseAsync` was added in v3.2.0. It allows registered `async` command handlers to be awaited. Always `await` its return value.
This quickstart demonstrates how to set up a multi-command CLI using `commist` with `parseAsync` for handling asynchronous operations. It shows command registration, argument parsing with `minimist`, strict command matching, and how to capture unmatched arguments. The example includes both synchronous and asynchronous command handlers.
import { fileURLToPath } from 'url';
import { dirname } from 'path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
// Minimalist CommonJS emulation for commist in ESM context
// In a pure CommonJS project, use: const commist = require('commist');
// and: const minimist = require('minimist');
import commistModule from 'commist';
const commist = commistModule.default || commistModule;
import minimistModule from 'minimist';
const minimist = minimistModule.default || minimistModule;
async function executeCommand(args) {
console.log(`Executing with args: ${JSON.stringify(args)}`);
return new Promise(resolve => setTimeout(resolve, 500));
}
async function doOtherStuff() {
console.log('Doing other stuff...');
return new Promise(resolve => setTimeout(resolve, 200));
}
const program = commist();
const argsToParse = process.argv.splice(2);
async function main() {
const result = await program
.register('start', async function(args) {
console.log('START command received.');
await executeCommand(args);
await doOtherStuff();
console.log('START command finished.');
})
.register('stop', function(args) {
args = minimist(args);
console.log('STOP command received with minimist args:', args);
})
.register({ command: 'config', strict: true }, async function(args) {
console.log('CONFIG command received (strict match).');
await executeCommand(args);
})
.parseAsync(argsToParse);
if (result) {
console.log('No command matched. Remaining arguments:', result);
console.log('Try: node your_script.js sta --port 3000');
console.log('Or: node your_script.js conf set --user admin');
}
}
main().catch(err => {
console.error('An error occurred:', err);
process.exit(1);
});
Errors
Common errors & fixes
TypeError: program.parseAsync is not a function
Attempting to use the `parseAsync` method with an older version of `commist` that predates its introduction.
fixUpgrade your `commist` package to v3.2.0 or newer: `npm install commist@latest`.
ReferenceError: minimist is not defined
While `commist` is designed to be used with `minimist` for argument parsing, `minimist` is not a direct runtime dependency of `commist` and must be installed and imported separately by the user.
fixInstall `minimist` (`npm install minimist`) and import it in your application, typically within your command handler functions: `const minimist = require('minimist');`. No command called, args [ 'your', 'command', 'and', 'args' ] (or similar output)
This message indicates that `commist` could not find a matching command. This could be due to a typo, using a command that isn't registered, or using `strict: true` on a command when the input doesn't match exactly, disabling fuzzy matching.
fixDouble-check command spelling, ensure the command is registered, or remove `strict: true` from the command registration if you intend to use `commist`'s fuzzy matching capabilities.
Audit
Dependencies
minimistrequiredExplicitly recommended and often required for parsing arguments within registered commands.