yargs

yargs the modern, pirate-themed successor to optimist.

CLI
yargs/yargsyargs.js.org/yargs

README

Yargs

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


ci [![NPM version][npm-image]][npm-url] [![js-standard-style][standard-image]][standard-url] [![Coverage][coverage-image]][coverage-url] [![Conventional Commits][conventional-commits-image]][conventional-commits-url] [![Slack][slack-image]][slack-url]

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:

  1. ```
  2. mocha [spec..]

  4. Run tests with Mocha

  6. Commands
  7.   mocha inspect [spec..]  Run tests with Mocha                         [default]
  8.   mocha init <path>       create a client-side Mocha setup at <path>

  10. Rules & Behavior
  11.   --allow-uncaught           Allow uncaught errors to propagate        [boolean]
  12.   --async-only, -A           Require all tests to use a callback (async) or
  13.                              return a Promise                          [boolean]
  14. ```

bash-completion shortcuts for commands and options.
and tons more.

Installation


Stable version:
  1. ``` sh
  2. npm i yargs
  3. ```

Bleeding edge version with the most recent features:
  1. ``` sh
  2. npm i yargs@next
  3. ```

Usage


Simple Example


  1. ``` js
  2. #!/usr/bin/env node
  3. const yargs = require('yargs/yargs')
  4. const { hideBin } = require('yargs/helpers')
  5. const argv = yargs(hideBin(process.argv)).argv

  7. if (argv.ships > 3 && argv.distance < 53.5) {
  8.   console.log('Plunder more riffiwobbles!')
  9. } else {
  10.   console.log('Retreat from the xupptumblers!')
  11. }
  12. ```

  1. ``` sh
  2. $ ./plunder.js --ships=4 --distance=22
  3. Plunder more riffiwobbles!

  5. $ ./plunder.js --ships 12 --distance 98.7
  6. Retreat from the xupptumblers!
  7. ```

Note: hideBin is a shorthand for [process.argv.slice(2)](https://nodejs.org/en/knowledge/command-line/how-to-parse-command-line-arguments/). It has the benefit that it takes into account variations in some environments, e.g., Electron.


Complex Example


  1. ``` js
  2. #!/usr/bin/env node
  3. const yargs = require('yargs/yargs')
  4. const { hideBin } = require('yargs/helpers')

  6. yargs(hideBin(process.argv))
  7.   .command('serve [port]', 'start the server', (yargs) => {
  8.     return yargs
  9.       .positional('port', {
  10.         describe: 'port to bind on',
  11.         default: 5000
  12.       })
  13.   }, (argv) => {
  14.     if (argv.verbose) console.info(`start server on :${argv.port}`)
  15.     serve(argv.port)
  16.   })
  17.   .option('verbose', {
  18.     alias: 'v',
  19.     type: 'boolean',
  20.     description: 'Run with verbose logging'
  21.   })
  22.   .parse()
  23. ```

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

Supported Platforms


TypeScript


yargs has type definitions at [@types/yargs][type-definitions].

  1. ```
  2. npm i @types/yargs --save-dev
  3. ```

See usage examples in docs.

Deno


As of v16, yargs supports Deno:

  1. ```typescript
  2. import yargs from 'https://deno.land/x/yargs/deno.ts'
  3. import { Arguments } from 'https://deno.land/x/yargs/deno-types.ts'

  5. yargs(Deno.args)
  6.   .command('download <files...>', 'download a list of files', (yargs: any) => {
  7.     return yargs.positional('files', {
  8.       describe: 'a list of files to do something with'
  9.     })
  10.   }, (argv: Arguments) => {
  11.     console.info(argv)
  12.   })
  13.   .strictCommands()
  14.   .demandCommand(1)
  15.   .parse()
  16. ```

ESM


As of v16,yargs supports ESM imports:

  1. ``` js
  2. import yargs from 'yargs'
  3. import { hideBin } from 'yargs/helpers'

  5. yargs(hideBin(process.argv))
  6.   .command('curl <url>', 'fetch the contents of the URL', () => {}, (argv) => {
  7.     console.info(argv)
  8.   })
  9.   .demandCommand(1)
  10.   .parse()
  11. ```

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


Yargs' API
Examples
Parsing Tricks
  Stop the Parser
  Negating Boolean Arguments
  Numbers
  Arrays
  Objects
  Quotes
Advanced Topics
  Composing Your App Using Commands
  Building Configurable CLI Apps
  Customizing Yargs' Parser
  Bundling yargs
Contributing

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](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).

[npm-url]: https://www.npmjs.com/package/yargs
[npm-image]: https://img.shields.io/npm/v/yargs.svg
[standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
[standard-url]: http://standardjs.com/
[conventional-commits-image]: https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg
[conventional-commits-url]: https://conventionalcommits.org/
[slack-image]: http://devtoolscommunity.herokuapp.com/badge.svg
[slack-url]: http://devtoolscommunity.herokuapp.com
[type-definitions]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs
[coverage-image]: https://img.shields.io/nycrc/yargs/yargs
[coverage-url]: https://github.com/yargs/yargs/blob/main/.nycrc