Named parameters with short and long keys for command-line use. Options provide flexible parameter handling with support for flags, arrays, validation, default values, and custom actions.
Options are created through a parent command and configured with chainable methods.
/**
* Create new option (called from Cmd.opt())
* @param cmd Parent command instance
*/
constructor(cmd: Cmd): Opt;Usage Examples:
const cmd = COA.Cmd()
.opt() // Creates new option
.name('verbose')
.short('v')
.long('verbose')
.flag()
.end(); // Return to parent commandConfigure option names and descriptions for CLI and help text.
/**
* Set canonical option identifier for internal use
* @param name Option name used in parsed options object
* @returns Option instance for chaining
*/
name(name: string): Opt;
/**
* Set option description for help text
* @param title Human-readable option description
* @returns Option instance for chaining
*/
title(title: string): Opt;Usage Examples:
const cmd = COA.Cmd()
.opt()
.name('outputDir') // Internal name
.title('Output directory') // Help text description
.short('o')
.long('output')
.end();Define how options are accessed from the command line.
/**
* Set short key for single-hyphen access (-x)
* @param short Single character for short option
* @returns Option instance for chaining
*/
short(short: string): Opt;
/**
* Set long key for double-hyphen access (--example)
* @param long String for long option name
* @returns Option instance for chaining
*/
long(long: string): Opt;Usage Examples:
const cmd = COA.Cmd()
.opt()
.name('config')
.short('c') // Accessible as -c
.long('config') // Accessible as --config
.title('Configuration file path')
.end();
// Usage: myapp -c config.json
// Usage: myapp --config=config.jsonConfigure how options handle values and behavior.
/**
* Make option a boolean flag (no value required)
* @returns Option instance for chaining
*/
flag(): Opt;
/**
* Allow option to accept multiple values
* @returns Option instance for chaining
*/
arr(): Opt;
/**
* Make option required
* @returns Option instance for chaining
*/
req(): Opt;
/**
* Make option act as command (exits after action)
* @returns Option instance for chaining
*/
only(): Opt;Usage Examples:
const cmd = COA.Cmd()
.opt()
.name('verbose')
.short('v')
.flag() // Boolean flag: -v
.end()
.opt()
.name('include')
.short('I')
.arr() // Multiple values: -I dir1 -I dir2
.end()
.opt()
.name('config')
.short('c')
.req() // Required option
.end()
.opt()
.name('version')
.long('version')
.only() // Exits after showing version
.act(function() {
return '1.0.0';
})
.end();Handle option value validation, transformation, and defaults.
/**
* Set validation/transformation function for option values
* @param validation Function to validate and/or transform values
* @returns Option instance for chaining
*/
val(validation: ValidationFunction): Opt;
/**
* Set default value for option
* @param def Default value (passed through validation)
* @returns Option instance for chaining
*/
def(def: any): Opt;
type ValidationFunction = (value: any) => any;Usage Examples:
const fs = require('fs');
const cmd = COA.Cmd()
.opt()
.name('port')
.short('p')
.val(function(port) {
const num = parseInt(port);
if (isNaN(num) || num < 1 || num > 65535) {
throw new Error('Port must be between 1 and 65535');
}
return num;
})
.def(3000)
.end()
.opt()
.name('config')
.short('c')
.val(function(path) {
if (!fs.existsSync(path)) {
throw new Error(`Config file not found: ${path}`);
}
return path;
})
.end();Built-in support for input and output streams with STDIN/STDOUT shortcuts.
/**
* Make option value an input stream (supports '-' for STDIN)
* @returns Option instance for chaining
*/
input(): Opt;
/**
* Make option value an output stream (supports '-' for STDOUT)
* @returns Option instance for chaining
*/
output(): Opt;Usage Examples:
const cmd = COA.Cmd()
.opt()
.name('input')
.short('i')
.input() // Accepts file path or '-' for STDIN
.def(process.stdin)
.end()
.opt()
.name('output')
.short('o')
.output() // Accepts file path or '-' for STDOUT
.def(process.stdout)
.end()
.act(function(opts) {
// opts.input is a readable stream
// opts.output is a writable stream
opts.input.pipe(opts.output);
});
// Usage: myapp -i input.txt -o output.txt
// Usage: myapp -i - -o - (STDIN to STDOUT)Define custom actions that execute when options are present.
/**
* Add action function that executes when option is present
* @param act Function called if option has any value
* @returns Option instance for chaining
*/
act(act: ActionFunction): Opt;
type ActionFunction = (
opts: any, // All parsed options
args: any[], // All parsed arguments
res?: any // Previous action results
) => any; // Return value or PromiseUsage Examples:
const cmd = COA.Cmd()
.opt()
.name('debug')
.short('d')
.flag()
.act(function(opts) {
console.log('Debug mode enabled');
process.env.DEBUG = '1';
})
.end()
.opt()
.name('version')
.long('version')
.only() // Exit after this action
.act(function() {
const pkg = require('./package.json');
return `Version: ${pkg.version}`;
})
.end();Custom completion functions for shell auto-completion.
/**
* Set custom completion function for option values
* @param fn Function that returns completion options
* @returns Option instance for chaining
*/
comp(fn: CompletionFunction): Opt;
type CompletionFunction = (opts: any) => any;Usage Examples:
const cmd = COA.Cmd()
.opt()
.name('format')
.short('f')
.comp(function(opts) {
return ['json', 'xml', 'yaml', 'csv'];
})
.end()
.opt()
.name('file')
.short('f')
.comp(function(opts) {
// Return file completions
const fs = require('fs');
return fs.readdirSync('.').filter(f => f.endsWith('.js'));
})
.end();Methods for managing the fluent interface chain.
/**
* End option configuration and return to parent command
* @returns Parent command instance
*/
end(): Cmd;
/**
* Apply function in option context
* @param args Variable arguments to apply
* @returns void
*/
apply(...args: any[]): void;
/**
* Return rejected promise for error handling
* @param args Variable arguments for rejection
* @returns void
*/
reject(...args: any[]): void;Usage Examples:
function addCommonOptions(option) {
return option
.val(function(v) { return v.trim(); })
.req();
}
const cmd = COA.Cmd()
.opt()
.name('username')
.short('u')
.apply(addCommonOptions) // Apply common configuration
.end()
.opt()
.name('password')
.short('p')
.apply(addCommonOptions)
.act(function(opts) {
if (opts.password.length < 8) {
this.reject('Password must be at least 8 characters');
}
})
.end();Options are parsed and made available in command actions.
Usage Examples:
const cmd = COA.Cmd()
.opt()
.name('verbose')
.short('v')
.flag()
.end()
.opt()
.name('files')
.short('f')
.arr() // Multiple values
.end()
.opt()
.name('output')
.short('o')
.def('output.txt')
.end()
.act(function(opts, args) {
console.log('Verbose mode:', opts.verbose); // boolean
console.log('Files:', opts.files); // array
console.log('Output:', opts.output); // string
if (opts.verbose) {
console.log('Processing files:', opts.files);
}
});
// Usage: myapp -v -f file1.txt -f file2.txt -o result.txt
// Parsed opts: { verbose: true, files: ['file1.txt', 'file2.txt'], output: 'result.txt' }