Have ideas to improve npm?Join in the discussion! »

    commandpost
    TypeScript icon, indicating that this package has built-in type declarations

    1.4.0 • Public • Published

    commandpost Circle CI

    commandpost is a command-line options parser. This library is inspired by commander.

    commander is very user-friendly, but not TypeScript-friendly. commandpost aims to improve this. Of course, commandpost can also be used from an ordinary JavaScript program. 👍

    Installation

    $ npm install --save commandpost
    

    How to Use

    Basic Usage

    $ cat cli.ts
    import * as commandpost from "commandpost";
    
    let root = commandpost
        .create<{ spice: string[]; }, { food: string; }>("dinner <food>")
        .version("1.0.0", "-v, --version")
        .description("today's dinner!")
        .option("-s, --spice <name>", "What spice do you want? default: pepper")
        .action((opts, args) => {
            console.log(`Your dinner is ${args.food} with ${opts.spice[0] || "pepper"}!`);
        });
    
    commandpost
        .exec(root, process.argv)
        .catch(err => {
            if (err instanceof Error) {
                console.error(err.stack);
            } else {
                console.error(err);
            }
            process.exit(1);
        });
    
    $ node cli.js --help
      Usage: dinner [options] [--] <food>
    
      Options:
    
        -s, --spice <name>  What spice do you want? default: pepper
    
    $ node cli.js -s "soy sause" "fillet steak"
    Your dinner is fillet steak with soy sause!
    

    Commands

    A top-level command is created by the commandpost.create function.

    commandpost also supports sub-commands. A sub-command is created by using the topLevelCommand.subCommand method. Refer to this example for a demonstration.

    commandpost can automatically generate help and command usage messages based on your configuration. For best results, it is recommended that you should set .version and .description for your top-level command.

    Options

    // shorthand & formal option with a required parameter. value is converted to string[].
    cmd.option("-c, --config <configFile>", "Read setting from specified config file path");
    
    // option with optional parameter. value is converted to string[].
    cmd.option("-c, --config [configFile]", "Read setting from specified config file path");
    
    // option without parameter (flag). option value is converted to boolean and defaults to `false`.
    cmd.option("--suppress-warning", "Suppress warning");
    
    // option with `--no-` prefix. option value is converted to boolean and defaults to true.
    cmd.option("--no-type-checking", "Type checking disabled");
    

    If you want to handle unknown options, you can use the .allowUnknownOption method.

    Arguments

    // required argument
    commandpost.create<{}, { food: string; }>("dinner <food>");
    
    // optional argument
    commandpost.create<{}, { food: string; }>("dinner [food]");
    
    // variadic argument
    commandpost.create<{}, { foods: string[]; }>("dinner <food...>");
    

    Examples

    Contributing

    This package's author, vvakame, is not a native English speaker. My first language is Japanese. If you find incorrect English, please send me a pull request.

    Keywords

    none

    Install

    npm i commandpost

    DownloadsWeekly Downloads

    67,563

    Version

    1.4.0

    License

    MIT

    Unpacked Size

    98.7 kB

    Total Files

    25

    Last publish

    Collaborators

    • avatar