Yargs be a node.js library fer hearties tryin' ter parse optstrings
Yargs helps you build interactive command line tools, by parsing arguments and generating an elegant user interface.
It gives you:
my-program.js serve --port=5000).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]
Stable version:
npm i yargs
Bleeding edge version with the most recent features:
npm i yargs@next
#!/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:
hideBinis a shorthand forprocess.argv.slice(2). It has the benefit that it takes into account variations in some environments, e.g., Electron.
#!/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.
yargs has type definitions at @types/yargs.
npm i @types/yargs --save-dev
See usage examples in docs.
As of v16, yargs supports Deno:
import yargs from 'https://deno.land/x/yargs@v17.7.2-deno/deno.ts'
import { Arguments } from 'https://deno.land/x/yargs@v17.7.2-deno/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()
Note: If you use version tags in url then you also have to add
-denoflag on the end, like@17.7.2-deno
See examples of using yargs in the browser in docs.
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.
18.0.0 (2025-05-26)
command.^20.19.0 || ^22.12.0 || >=23.command. (d90af45)^20.19.0 || ^22.12.0 || >=23. (d90af45)Commander is another popular npm package for parsing command-line options. It provides a high-level API for defining commands and options, similar to yargs. Commander is known for its simplicity and declarative approach to command-line arguments.
Minimist is a minimalistic command-line argument parser. It is more lightweight than yargs and focuses on parsing a list of arguments into an object, without the additional features like command handling, help text generation, or validation.
Meow is a CLI helper for creating Node.js command-line apps. It provides a simpler and more opinionated API compared to yargs, with built-in help text, version output, and flag aliasing. Meow is suitable for smaller projects that require less customization.
Caporal is a full-featured framework for building command-line applications. It offers a rich set of features including argument parsing, validation, autocomplete, and more. Caporal is more framework-like compared to yargs, which might be more suitable for complex CLI tools.
FAQs
yargs the modern, pirate-themed, successor to optimist.
The npm package yargs receives a total of 101,549,899 weekly downloads. As such, yargs popularity was classified as popular.
We found that yargs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket researchers uncover how threat actors weaponize Discord across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.
Security News
Socket now integrates with Bun 1.3’s Security Scanner API to block risky packages at install time and enforce your organization’s policies in local dev and CI.
Research
The Socket Threat Research Team is tracking weekly intrusions into the npm registry that follow a repeatable adversarial playbook used by North Korean state-sponsored actors.