yargs
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/yargs package

    17.2.0 • Public • Published

    Yargs

    Yargs be a node.js library fer hearties tryin' ter parse optstrings


    ci NPM version js-standard-style Coverage Conventional Commits Slack

    Description

    Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface.

    It gives you:

    • commands and (grouped) options (my-program.js serve --port=5000).
    • a dynamically generated help menu based on your arguments:
    mocha [spec..]
    
    Run tests with Mocha
    
    Commands
      mocha inspect [spec..]  Run tests with Mocha                         [default]
      mocha init <path>       create a client-side Mocha setup at <path>
    
    Rules & Behavior
      --allow-uncaught           Allow uncaught errors to propagate        [boolean]
      --async-only, -A           Require all tests to use a callback (async) or
                                 return a Promise                          [boolean]
    
    • bash-completion shortcuts for commands and options.
    • and tons more.

    Installation

    Stable version:

    npm i yargs

    Bleeding edge version with the most recent features:

    npm i yargs@next

    Usage

    Simple Example

    #!/usr/bin/env node
    const yargs = require('yargs/yargs')
    const { hideBin } = require('yargs/helpers')
    const argv = yargs(hideBin(process.argv)).argv
    
    if (argv.ships > 3 && argv.distance < 53.5) {
      console.log('Plunder more riffiwobbles!')
    } else {
      console.log('Retreat from the xupptumblers!')
    }
    $ ./plunder.js --ships=4 --distance=22
    Plunder more riffiwobbles!
    
    $ ./plunder.js --ships 12 --distance 98.7
    Retreat from the xupptumblers!

    Note: hideBin is a shorthand for process.argv.slice(2). It has the benefit that it takes into account variations in some environments, e.g., Electron.

    Complex Example

    #!/usr/bin/env node
    const yargs = require('yargs/yargs')
    const { hideBin } = require('yargs/helpers')
    
    yargs(hideBin(process.argv))
      .command('serve [port]', 'start the server', (yargs) => {
        return yargs
          .positional('port', {
            describe: 'port to bind on',
            default: 5000
          })
      }, (argv) => {
        if (argv.verbose) console.info(`start server on :${argv.port}`)
        serve(argv.port)
      })
      .option('verbose', {
        alias: 'v',
        type: 'boolean',
        description: 'Run with verbose logging'
      })
      .argv

    Run the example above with --help to see the help for the application.

    Supported Platforms

    TypeScript

    yargs has type definitions at @types/yargs.

    npm i @types/yargs --save-dev
    

    See usage examples in docs.

    Deno

    As of v16, yargs supports Deno:

    import yargs from 'https://deno.land/x/yargs/deno.ts'
    import { Arguments } from 'https://deno.land/x/yargs/deno-types.ts'
    
    yargs(Deno.args)
      .command('download <files...>', 'download a list of files', (yargs: any) => {
        return yargs.positional('files', {
          describe: 'a list of files to do something with'
        })
      }, (argv: Arguments) => {
        console.info(argv)
      })
      .strictCommands()
      .demandCommand(1)
      .argv

    ESM

    As of v16,yargs supports ESM imports:

    import yargs from 'yargs'
    import { hideBin } from 'yargs/helpers'
    
    yargs(hideBin(process.argv))
      .command('curl <url>', 'fetch the contents of the URL', () => {}, (argv) => {
        console.info(argv)
      })
      .demandCommand(1)
      .argv

    Usage in Browser

    See examples of using yargs in the browser in docs.

    Community

    Having problems? want to contribute? join our community slack.

    Documentation

    Table of Contents

    Supported Node.js Versions

    Libraries in this ecosystem make a best effort to track Node.js' release schedule. Here's a post on why we think this is important.

    Install

    npm i yargs

    DownloadsWeekly Downloads

    61,258,924

    Version

    17.2.0

    License

    MIT

    Unpacked Size

    296 kB

    Total Files

    60

    Last publish

    Collaborators

    • bcoe
    • oss-bot