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]

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]

• generate completion scripts for Bash and Zsh for your command
• and tons more.

Installation

Using npm for example:

npm i yargs

Usage

Simple Example

#!/usr/bin/env node
import yargs from 'yargs';
import {hideBin} from 'yargs/helpers';
const argv = yargs(hideBin(process.argv)).parse();
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
import yargs from 'yargs';
import {hideBin} from '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][type-definitions].

npm i @types/yargs --save-dev

See usage examples in docs.

Usage in Browser

See examples of using yargs in the browser in docs.

Documentation

Table of Contents

• Yargs' API
• Examples
• Parsing Tricks

• Advanced Topics

• Contributing

Support

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.

The current version of yargs is fully supported on Long Term Support versions of Node.js, and requires at least v20.19.0.

Older major versions of yargs receive security updates for 12 months. For more see: Release Policy.

The main forum for free and community support is the project Issues on GitHub.

Special Thanks

HeroDevs sponsored the yargs projects with a donation from its Open Source Sustainability Fund in 2026.

[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/ [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