Guide · Open source

How to use yargs: parse flags, build subcommands and help menus

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Yargs is a Node.js library that reads the options and commands a user types into a terminal and turns them into values your JavaScript program can use. This guide is for developers building command line tools who want flags, subcommands and a help menu without writing the parsing code by hand. By the end you will know how to install it, parse flags, define a command with a positional argument, and where to look for completion and TypeScript support.

yargsyargs/yargs · ★ 11.5k · MIT Install options & downloads

Quick start

1Install yargs. Run npm i yargs in your Node.js project folder.
2Read the arguments. Create a script and parse arguments with yargs(hideBin(process.argv)).parse().
3Define options. Add flags with .option(), giving each an alias, type and description where needed.
4Add a command. Use .command() with a signature like 'serve [port]', a description and a handler.
5Check the help menu. Run your program with --help to see the menu yargs generated from your definitions.
6Add TypeScript types (optional). In a TypeScript project, run npm i @types/yargs --save-dev.

Install yargs with npm

Yargs is a package you add to a Node.js project. The README installs it with npm, the package manager that ships with Node.js.

The README does not state a minimum Node.js version. Check the project's documentation for supported versions.
If your project uses TypeScript, the README lists optional type definitions in a separate package.

npm i yargs

Parse flags from the command line

Pass the arguments to yargs with hideBin, which removes the first two entries of process.argv. Yargs then exposes each flag as a property on the parsed result. Values are read as the README example shows: --ships=4 and --ships 4 both set the same value.

The README's example checks two numeric flags and prints a message depending on their values. Run it with different inputs to see the parsed values change.

hideBin(process.argv) is a shorthand for process.argv.slice(2), and it also handles some environments such as Electron.
Declare an option with .option() to give it an alias, a type and a description, as the complex example does with --verbose and -v.

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

Add commands and positional arguments

Commands let one program offer several actions, such as serve or init. Use .command() with a signature string, a description, an optional builder function that declares positional arguments, and a handler that runs when the command is typed.

The example below defines a serve command with an optional port argument that defaults to 5000, plus a global verbose flag.

The signature 'serve [port]' makes port optional; square brackets mark optional arguments in this syntax.
Use yargs.positional() inside the builder to set describe and default for an argument.

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();

Yargs builds a help menu from the options and commands you define, so you do not write usage text by hand. Run your program with --help to see it. The README shows a sample menu that lists commands and groups options under headings such as Rules & Behavior.

Each option's description and type appear in the menu, for example [boolean] next to a flag.
The menu is generated from your definitions, so adding an option also updates the help output.

Generate Bash and Zsh completion

The README says yargs can generate completion scripts for Bash and Zsh for your command. Check the linked API documentation for how to enable and install them, because the README itself does not show those steps.

Use TypeScript type definitions

Yargs has type definitions published as @types/yargs. Install them as a development dependency in a TypeScript project. The README points to the TypeScript usage docs for examples.

npm i @types/yargs --save-dev

What people use it for

Building a CLI with subcommands such as serve or init, each with its own flags.
Giving a team tool an automatically generated --help menu that stays in sync with its options.
Shipping Bash or Zsh completion for a command-line program, per the README's feature list.
Adding typed argument parsing to a TypeScript command line application.

Frequently asked questions

How do I install yargs?

Run npm i yargs in your project folder, as the README shows. You need Node.js and npm installed first.

Is yargs free to use?

The project is licensed under the MIT licence, as listed on its repository page. Check the LICENSE file in the repository for the full terms.

What do I need to run yargs?

You need Node.js and npm. The README does not specify a minimum Node.js version, and it notes the project aims to track Node.js' release schedule.

Does yargs work in the browser?

The README says yargs can be used in the browser and links to examples in the browser docs. Those examples are in the project's documentation.

What are alternatives to yargs?

The project lists commander, minimist, oclif and meow as comparable projects. Simple scripts that only read process.argv may not need any of them.

Why does my help menu not show my options?

The help menu is built from the options and commands you define with .option() and .command(). Make sure each option is declared before calling .parse(), then run your program with --help again.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose yargs if you are a Node.js developer building a command line tool with subcommands, flags and a generated help menu. Skip it for a very simple script that only reads process.argv, for non-developer end-user apps, or for projects that do not use JavaScript; the README suggests commander, minimist, oclif or meow as comparable options.

Install options & downloads