Yargs: argv parsing, a generated help screen, and an ESM-only package

Yargs parses the arguments and prints the help screen it generated

Yargs does two jobs, and most hand-rolled parsers do only the first. It turns `process.argv` into named options, and it renders a help screen from those same declarations, so the usage text cannot drift away from the parser the way a hand-written `--help` string does.

Four things come out of that. Commands with grouped options, invoked as `my-program.js serve --port=5000`. A help menu built from the argument definitions rather than typed out by you. Completion scripts for Bash and Zsh. And a long API reference at /docs/api.md that the README summarises as tons more.

The description line calls it the modern, pirate-themed successor to optimist, and the dependency list explains the shape that history produced. The parsing core is a separate package, `yargs-parser`, and the terminal interface is another one, `cliui`. Yargs is the layer that joins them and decides what your tool's screen looks like.

The target is a command line tool, not a general-purpose parsing library. Every feature in the documentation is oriented at someone about to print a screen for a human.

hideBin is there because Electron puts its own arguments first

Installing is one command:

npm i yargs

The smallest complete program is this, and the two imports are the whole setup:

#!/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!');
}

Running it shows that numeric options arrive as numbers, not as strings, which is the part that saves you from writing your own coercion:

$ ./plunder.js --ships=4 --distance=22
Plunder more riffiwobbles!

$ ./plunder.js --ships 12 --distance 98.7
Retreat from the xupptumblers!

`hideBin` is the piece people skip and then debug for an afternoon. It is shorthand for `process.argv.slice(2)`, with the difference that it accounts for variations in some environments, Electron being the one named in the docs.

type: module closes the require path, and the .cjs examples are the leftover

The package manifest is where a reader looking for upgrade cost should start. Version 18.2.0 declares `"type": "module"`, sets `main` to `./index.mjs`, and exposes an exports map with five entries: `./package.json`, `./helpers` resolving to `./helpers/helpers.mjs`, `./browser` carrying its own `types` and `import` conditions, and both `.` and `./yargs` resolving to `./index.mjs`.

Two consequences. Yargs is an ES module with an `.mjs` entry point, so a codebase that has not moved to ESM should load it with a dynamic import or migrate first. And the helper is a subpath export rather than a property on the default export, so `yargs/helpers` is a real specifier you have to get right.

The example directory shows the seam. `example/count.mjs`, `example/nested.mjs`, `example/help.mjs` and `example/complex.mjs` sit next to `example/bool.cjs`, `example/boolean_double.cjs` and `example/boolean_single.cjs`. Three CommonJS files surviving among a directory of ES modules is the trace of the format change, and they are the files to read if you want to know what the older calling convention looked like. The top-level `deno.ts` and `deno-types.ts` entries show the package is also reachable outside Node, through its own entry files.

TypeScript types are a second install, and the files array negates every .d.ts

Yargs does not ship its own type definitions. The README points at DefinitelyTyped and tells you to install them yourself:

npm i @types/yargs --save-dev

The manifest agrees, and the mechanics are visible. The `files` array that controls what lands in the published tarball lists `browser.d.ts` early on, includes `helpers/*.js`, `index.mjs`, `build`, `locales` and `lib/platform-shims/*.mjs`, and then closes with two negation patterns that exclude declaration files at the package root and in every subdirectory. The exports map nevertheless routes the `browser` condition's `types` at `./browser.d.ts`.

For a reader the practical outcome is a second version line to track. The runtime package moves on its own release schedule and the type definitions move on DefinitelyTyped's, and the two are not published together. A TypeScript project that upgrades yargs and does not upgrade `@types/yargs` is working against a mismatch, and the errors it produces are about types rather than about behaviour.

The usage examples the README points to live in docs/typescript.md, which is where you should look before deciding whether the declarations cover the command shape you are building.

yargs-parser is the dependency to take when you want the parse and not the screen

The runtime dependency list is six entries, and each one tells you what a piece of the output costs: `cliui` at ^9.0.1 and `string-width` at ^8.2.1 for the aligned table, `y18n` at ^5.0.5 with the top-level `locales` directory for the translated strings, `escalade` at ^3.1.1 and `get-caller-file` at ^2.0.5, and `yargs-parser` at ^22.0.0 for the parsing itself.

The layout of the generated help is visible in the sample the README uses, taken from Mocha's own output. Option groups get a heading such as `Rules & Behavior`, types are annotated in a right-hand column as `[boolean]`, defaults are marked `[default]`, and long descriptions wrap onto a second line aligned under the first. Producing that alignment is what `cliui` and `string-width` are for, and it is why the help output is computed at run time rather than baked into your binary.

If you only want `process.argv` turned into an object, `yargs-parser` is the smaller dependency and you take on writing the screen yourself. Yargs keeps a `Customizing Yargs' Parser` page in docs/advanced.md for people who want the interface and need to change the parser underneath it.

Completion is generated for Bash and Zsh, and for nothing else

The shell completion is one of the four things yargs claims, and it is scoped to two shells: completion scripts for Bash and Zsh. Fish, PowerShell and Nushell are not mentioned anywhere in the README or the documentation index.

For a reader on one of those shells, the consequence is that this feature does not exist for you, and the gap is not something the CLI papers over. If your user base is on fish, the help screen still works and the tab completion of subcommands and flags does not.

There is a second, smaller gap on the same feature. The scripts are described as generated, which means your tool has to emit them and the user has to install them somewhere. The README does not document the command that produces the script or the path it should be written to, so a project shipping completion has to work that out from the API reference rather than from a documented recipe.

The feature surface lives in docs pages the README only lists by title

The README is an index more than a manual, and for a project this size that is reasonable. docs/tricks.md is broken into Stop the Parser, Negating Boolean Arguments, Numbers, Arrays, Objects and Quotes. docs/advanced.md covers Composing Your App Using Commands, Building Configurable CLI Apps and Customizing Yargs' Parser. Anything specific you need lives one level down.

The `example/` directory is the more honest map, because the filenames are the feature names: `requires_arg.mjs`, `implies.mjs`, `nested.mjs`, `nonopt.mjs`, `count.mjs`, `short.mjs`, `divide.mjs`, `string.mjs`, `line_count_wrap.mjs`, `default_hash.mjs`, `command_hierarchy.mjs`, `usage-options.mjs`, and `yargs.html` for the browser build. Twenty-four files plus a cmds/ directory.

Two things about maintenance are worth stating concretely. The repository's last push was on 2026-10-31, and the three most recent tags are v17.7.3 from 2026-06-19, v18.1.0 from 2026-07-26 and v18.2.0 from 2026-09-20. On Node.js support the README states only that libraries in this ecosystem make a best effort to track the release schedule, and it does not give a minimum version, so the floor has to come from the package engines field or from your own build.

Editorial conclusion

Adopt yargs when your tool is meant to be read by a human who has to remember a flag, because the help screen and the parser come from one declaration. Do not adopt it to parse argv in a library or a worker where the generated help is dead weight, and check the module format before you start, because version 18 declares type module and a CommonJS host has to load it with a dynamic import. The first thing to verify in your own repository is that node_modules keeps cliui, string-width and y18n reachable, since the help output is rendered and localized at runtime rather than precompiled.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. yargs/yargs on GitHub