yargs
yargs the modern, pirate-themed, successor to optimist.
Last updated 25 days ago by oss-bot .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install yargs 
SYNC missed versions from official npm registry.

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'
  })
  .parse()

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)
  .parse()

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)
  .parse()

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.

Current Tags

  • 17.2.1                                ...           latest (25 days ago)
  • 11.1.1                                ...           latest-11 (2 years ago)
  • 13.3.2                                ...           latest-13 (2 years ago)
  • 14.2.3                                ...           latest-14 (2 years ago)
  • 7.1.2                                ...           latest-7 (6 months ago)
  • 17.1.1-candidate.0                                ...           next (2 months ago)
  • 14.2.1                                ...           next-14 (2 years ago)
  • 15.5.0-candidate.0                                ...           next-15 (8 months ago)

238 Versions

  • 17.2.1                                ...           25 days ago
  • 17.2.0                                ...           a month ago
  • 17.1.1                                ...           2 months ago
  • 17.1.1-candidate.0                                ...           2 months ago
  • 17.1.0                                ...           3 months ago
  • 17.1.0-candidate.0                                ...           3 months ago
  • 17.0.2-candidate.1                                ...           3 months ago
  • 17.0.2-candidate                                ...           3 months ago
  • 17.0.1                                ...           6 months ago
  • 17.0.0                                ...           6 months ago
  • 17.0.0-candidate.13                                ...           6 months ago
  • 7.1.2                                ...           6 months ago
  • 17.0.0-candidate.12                                ...           6 months ago
  • 17.0.0-candidate.11                                ...           6 months ago
  • 17.0.0-candidate.10                                ...           7 months ago
  • 17.0.0-candidate.9                                ...           7 months ago
  • 17.0.0-candidate.8                                ...           7 months ago
  • 17.0.0-candidate.7                                ...           7 months ago
  • 17.0.0-candidate.6                                ...           7 months ago
  • 17.0.0-candidate.5                                ...           7 months ago
  • 17.0.0-candidate.4                                ...           7 months ago
  • 17.0.0-candidate.3                                ...           8 months ago
  • 15.5.0-candidate.0                                ...           8 months ago
  • 17.0.0-candidate.2                                ...           8 months ago
  • 17.0.0-candidate.1                                ...           8 months ago
  • 17.0.0-candidate.0                                ...           9 months ago
  • 16.2.0                                ...           a year ago
  • 16.1.1                                ...           a year ago
  • 16.1.0                                ...           a year ago
  • 16.0.4-candidate.0                                ...           a year ago
  • 16.0.3                                ...           a year ago
  • 16.0.2                                ...           a year ago
  • 16.0.1                                ...           a year ago
  • 16.0.0                                ...           a year ago
  • 16.0.0-beta.3                                ...           a year ago
  • 16.0.0-beta.2                                ...           a year ago
  • 16.0.0-beta.1                                ...           a year ago
  • 16.0.0-beta.0                                ...           a year ago
  • 16.0.0-alpha.3                                ...           a year ago
  • 16.0.0-alpha.2                                ...           a year ago
  • 16.0.0-alpha.1                                ...           a year ago
  • 16.0.0-alpha.0                                ...           a year ago
  • 15.4.1                                ...           a year ago
  • 15.4.0                                ...           a year ago
  • 15.4.0-beta.1                                ...           a year ago
  • 7.1.1                                ...           a year ago
  • 15.4.0-beta.0                                ...           a year ago
  • 15.3.2-beta.0                                ...           2 years ago
  • 15.3.1                                ...           2 years ago
  • 13.3.2                                ...           2 years ago
  • 14.2.3                                ...           2 years ago
  • 15.3.1-beta.0                                ...           2 years ago
  • 15.3.0                                ...           2 years ago
  • 15.3.0-beta.1                                ...           2 years ago
  • 15.3.0-beta.0                                ...           2 years ago
  • 15.2.0                                ...           2 years ago
  • 15.2.0-beta.2                                ...           2 years ago
  • 15.2.0-beta.1                                ...           2 years ago
  • 15.2.0-beta.0                                ...           2 years ago
  • 15.1.0                                ...           2 years ago
  • 14.2.2                                ...           2 years ago
  • 15.0.2                                ...           2 years ago
  • 15.0.1                                ...           2 years ago
  • 15.0.0                                ...           2 years ago
  • 14.2.1                                ...           2 years ago
  • 11.1.1                                ...           2 years ago
  • 14.2.0                                ...           2 years ago
  • 14.1.0                                ...           2 years ago
  • 14.0.0                                ...           2 years ago
  • 13.3.0                                ...           2 years ago
  • 13.2.4                                ...           2 years ago
  • 13.2.2                                ...           3 years ago
  • 13.2.1                                ...           3 years ago
  • 13.2.0                                ...           3 years ago
  • 13.1.0                                ...           3 years ago
  • 13.0.0-candidate.0                                ...           3 years ago
  • 12.0.5                                ...           3 years ago
  • 12.0.4                                ...           3 years ago
  • 12.0.3-candidate.0                                ...           3 years ago
  • 12.0.2                                ...           3 years ago
  • 12.0.1                                ...           3 years ago
  • 12.0.0                                ...           3 years ago
  • 12.0.0-candidate.0                                ...           4 years ago
  • 11.1.0                                ...           4 years ago
  • 11.0.0                                ...           4 years ago
  • 10.1.2                                ...           4 years ago
  • 10.1.1                                ...           4 years ago
  • 10.1.0                                ...           4 years ago
  • 10.0.3                                ...           4 years ago
  • 10.0.2                                ...           4 years ago
  • 10.0.1                                ...           4 years ago
  • 10.0.0                                ...           4 years ago
  • 10.0.0-alpha.4                                ...           4 years ago
  • 10.0.0-alpha.3                                ...           4 years ago
  • 10.0.0-alpha.2                                ...           4 years ago
  • 10.0.0-alpha.1                                ...           4 years ago
  • 10.0.0-alpha.0                                ...           4 years ago
  • 9.0.1                                ...           4 years ago
  • 9.0.0                                ...           4 years ago
  • 8.0.2                                ...           4 years ago
  • 8.0.1                                ...           4 years ago
  • 8.0.0                                ...           4 years ago
  • 8.0.0-candidate.1                                ...           4 years ago
  • 8.0.0-candidate.0                                ...           5 years ago
  • 7.1.0                                ...           5 years ago
  • 7.0.2                                ...           5 years ago
  • 7.0.2-candidate.1                                ...           5 years ago
  • 7.0.1                                ...           5 years ago
  • 7.0.0                                ...           5 years ago
  • 7.0.0-alpha.3                                ...           5 years ago
  • 7.0.0-alpha.2                                ...           5 years ago
  • 7.0.0-alpha.1                                ...           5 years ago
  • 6.6.1-candidate.4                                ...           5 years ago
  • 6.6.1-candidate.3                                ...           5 years ago
  • 6.6.1-candidate.2                                ...           5 years ago
  • 6.6.1-candidate.1                                ...           5 years ago
  • 6.6.1-candidate.0                                ...           5 years ago
  • 6.6.0                                ...           5 years ago
  • 6.6.0-candidate.0                                ...           5 years ago
  • 6.5.0                                ...           5 years ago
  • 6.4.0                                ...           5 years ago
  • 6.3.0                                ...           5 years ago
  • 6.3.0-candidate                                ...           5 years ago
  • 6.2.0                                ...           5 years ago
  • 6.2.0-candidate                                ...           5 years ago
  • 6.1.1                                ...           5 years ago
  • 6.1.1-candidate                                ...           5 years ago
  • 6.1.0-candidate                                ...           5 years ago
  • 6.0.0                                ...           5 years ago
  • 6.0.0-alpha.1                                ...           5 years ago
  • 5.0.0                                ...           5 years ago
  • 5.0.0-candidate                                ...           5 years ago
  • 4.8.1                                ...           5 years ago
  • 4.8.1-candidate                                ...           5 years ago
  • 4.8.0                                ...           5 years ago
  • 4.8.0-candidate3                                ...           5 years ago
  • 4.8.0-candidate2                                ...           5 years ago
  • 4.8.0-candidate                                ...           5 years ago
  • 4.7.1                                ...           5 years ago
  • 4.7.0                                ...           5 years ago
  • 4.7.0-pre                                ...           5 years ago
  • 4.6.0                                ...           6 years ago
  • 4.6.0-candidate                                ...           6 years ago
  • 4.5.0                                ...           6 years ago
  • 4.4.0                                ...           6 years ago
  • 4.3.2                                ...           6 years ago
  • 4.3.1                                ...           6 years ago
  • 4.3.0                                ...           6 years ago
  • 4.2.0                                ...           6 years ago
  • 4.1.0                                ...           6 years ago
  • 4.0.0                                ...           6 years ago
  • 4.0.0-alpha5                                ...           6 years ago
  • 4.0.0-alpha4                                ...           6 years ago
  • 4.0.0-alpha3                                ...           6 years ago
  • 4.0.0-alpha2                                ...           6 years ago
  • 4.0.0-alpha1                                ...           6 years ago
  • 3.32.0                                ...           6 years ago
  • 3.31.0                                ...           6 years ago
  • 3.30.0                                ...           6 years ago
  • 3.29.0                                ...           6 years ago
  • 3.28.0                                ...           6 years ago
  • 3.27.0                                ...           6 years ago
  • 3.26.0                                ...           6 years ago
  • 3.25.0                                ...           6 years ago
  • 3.24.0                                ...           6 years ago
  • 3.23.0                                ...           6 years ago
  • 3.22.2                                ...           6 years ago
  • 3.22.1                                ...           6 years ago
  • 3.22.0                                ...           6 years ago
  • 3.21.1                                ...           6 years ago
  • 3.21.0                                ...           6 years ago
  • 3.20.0                                ...           6 years ago
  • 3.19.0                                ...           6 years ago
  • 3.18.1                                ...           6 years ago
  • 3.18.0                                ...           6 years ago
  • 3.17.1                                ...           6 years ago
  • 3.16.1                                ...           6 years ago
  • 3.16.0                                ...           6 years ago
  • 3.15.0                                ...           6 years ago
  • 3.14.0                                ...           6 years ago
  • 3.13.0                                ...           6 years ago
  • 3.12.0                                ...           6 years ago
  • 3.11.0                                ...           6 years ago
  • 3.10.0                                ...           6 years ago
  • 3.9.1                                ...           6 years ago
  • 3.9.0                                ...           6 years ago
  • 3.8.0                                ...           6 years ago
  • 3.7.2                                ...           7 years ago
  • 3.7.1                                ...           7 years ago
  • 3.7.0                                ...           7 years ago
  • 3.6.0                                ...           7 years ago
  • 3.5.4                                ...           7 years ago
  • 3.5.3                                ...           7 years ago
  • 3.5.2                                ...           7 years ago
  • 3.5.1                                ...           7 years ago
  • 3.5.0                                ...           7 years ago
  • 3.4.5                                ...           7 years ago
  • 3.4.4                                ...           7 years ago
  • 3.4.0                                ...           7 years ago
  • 3.3.1                                ...           7 years ago
  • 3.2.1                                ...           7 years ago
  • 3.1.0                                ...           7 years ago
  • 3.0.4                                ...           7 years ago
  • 3.0.3                                ...           7 years ago
  • 3.0.2                                ...           7 years ago
  • 3.0.1                                ...           7 years ago
  • 3.0.0                                ...           7 years ago
  • 2.3.0                                ...           7 years ago
  • 2.1.1                                ...           7 years ago
  • 1.3.3                                ...           7 years ago
  • 1.3.2                                ...           7 years ago
  • 1.3.1                                ...           7 years ago
  • 1.3.0                                ...           7 years ago
  • 1.2.6                                ...           7 years ago
  • 1.2.5                                ...           7 years ago
  • 1.2.4                                ...           7 years ago
  • 1.2.3                                ...           7 years ago
  • 1.2.2                                ...           7 years ago
  • 1.2.1                                ...           8 years ago
  • 1.2.0                                ...           8 years ago
  • 1.1.3                                ...           8 years ago
  • 1.1.2                                ...           8 years ago
  • 1.1.1                                ...           8 years ago
  • 1.1.0                                ...           8 years ago
  • 1.0.15                                ...           8 years ago
  • 1.0.13                                ...           8 years ago
  • 1.0.12                                ...           8 years ago
  • 1.0.11                                ...           8 years ago
  • 1.0.10                                ...           8 years ago
  • 1.0.9                                ...           8 years ago
  • 1.0.8                                ...           8 years ago
  • 1.0.7                                ...           8 years ago
  • 1.0.6                                ...           8 years ago
  • 1.0.5                                ...           8 years ago
  • 1.0.4                                ...           8 years ago
  • 1.0.3                                ...           8 years ago
  • 1.0.1                                ...           8 years ago
  • 1.0.0                                ...           8 years ago
Maintainers (2)
Downloads
Today 107,768
This Week 618,475
This Month 2,091,059
Last Day 168,306
Last Week 913,870
Last Month 3,993,144
Dependencies (7)
Dev Dependencies (22)
Dependents (26301)