yargs

yargs the modern, pirate-themed, successor to optimist.

weekly downloads145.0M

versionv18.0.0

licenseMIT

categorytoolchain

argumentargsoptionparserparsingclicommand

Overview

Yargs is a battle-tested command-line argument parser designed for building production-grade CLI applications in Node.js. Unlike minimalist parsers that simply extract flags and values, yargs provides a complete framework for creating interactive command-line interfaces with minimal boilerplate. It handles the complex orchestration of subcommands, positional arguments, option validation, and user-facing documentation automatically.

With over 145 million weekly downloads, yargs powers critical developer tools across the JavaScript ecosystem including Mocha, Webpack CLI, and Angular CLI. Its adoption stems from a pragmatic API that eliminates tedious manual parsing logic while maintaining flexibility for advanced use cases. The package evolved as the successor to optimist, refining years of CLI development patterns into a chainable, declarative interface.

Yargs excels at transforming raw process.argv arrays into structured data through type coercion, validation rules, and middleware-style command handlers. It automatically generates formatted help text, usage examples, and even shell completion scripts for Bash and Zsh. For teams building developer tools, build systems, or any application requiring rich command-line interaction, yargs reduces implementation time from hours to minutes while maintaining professional UX standards.

The library targets intermediate to advanced JavaScript developers who need more than basic flag parsing but want to avoid reimplementing standard CLI patterns. Its builder-style API supports both CommonJS and ES modules, with modern features like async command handlers and configuration file integration through package.json conventions.

Quick Start

typescript

import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';
import fs from 'fs/promises';

const argv = yargs(hideBin(process.argv))
  .command(
    'deploy <environment>',
    'Deploy application to specified environment',
    (yargs) => {
      return yargs
        .positional('environment', {
          describe: 'Target environment',
          choices: ['staging', 'production'],
          type: 'string'
        })
        .option('dry-run', {
          alias: 'd',
          type: 'boolean',
          description: 'Simulate deployment without applying changes'
        })
        .option('version', {
          alias: 'v',
          type: 'string',
          demandOption: true,
          description: 'Version tag to deploy'
        });
    },
    async (argv) => {
      console.log(`Deploying v${argv.version} to ${argv.environment}`);
      if (argv.dryRun) {
        console.log('[DRY RUN] No changes applied');
        return;
      }
      await fs.writeFile(
        './deploy.log',
        `${new Date().toISOString()}: ${argv.environment}@${argv.version}\n`,
        { flag: 'a' }
      );
      console.log('Deployment complete');
    }
  )
  .option('config', {
    alias: 'c',
    type: 'string',
    description: 'Path to configuration file'
  })
  .demandCommand(1, 'You must provide a command')
  .strict()
  .help()
  .parse();

Use Cases

Build tools and task runners: Create npm scripts with complex workflows like build systems that accept environment flags, output directories, and watch modes. Yargs handles the argument matrix while you focus on business logic (e.g., build --env production --sourcemaps --watch).

Database migration CLIs: Implement commands like migrate up, migrate down --steps 3, or migrate create users with positional arguments and options. Yargs' subcommand architecture maps naturally to CRUD operations and administrative tasks.

Code generators and scaffolding tools: Build yeoman-style generators that prompt for project types, feature flags, and configuration presets. Combine yargs with prompts libraries for interactive wizards that fall back to non-interactive mode with full flag support.

DevOps automation scripts: Construct deployment tools that parse server targets, rollback options, and dry-run modes. The strict validation and type coercion prevent production mistakes from malformed arguments.

Testing framework runners: Design test CLIs with reporters, file patterns, parallelization flags, and coverage thresholds. Yargs' middleware system allows preprocessing arguments before test execution, mirroring how Mocha itself uses the library.

Pros & Cons

Pros

+Zero-effort help generation and shell completion scripts eliminate documentation boilerplate entirely
+Subcommand architecture with builder functions scales elegantly from simple scripts to complex multi-level CLIs
+Comprehensive validation (type coercion, required options, conflicts, implications) catches user errors before your code runs
+Mature ecosystem integration with plugin support via configuration extends and package.json loading
+Excellent TypeScript support with detailed type definitions for autocomplete and compile-time safety

Cons

−Heavier bundle size (compared to minimist/meow) adds ~200KB to dependencies, problematic for size-constrained environments
−Learning curve for advanced features like middleware, command modules, and strict mode configuration
−Automatic type coercion can cause surprising behavior (e.g., numeric strings converted unexpectedly) without explicit configuration
−Overkill for simple scripts that only need 2-3 flags; setup overhead outweighs benefits in trivial cases
−Error messages for misconfigured commands can be cryptic when chaining many validation rules together

Alternatives

commanderv14.0.3

the complete solution for node.js command-line programs

toolchaincommandercommand

CLI app helper

Comparisons

commander vs yargs

toolchain

Install

bash

npm install yargs

bash

pnpm add yargs

bash

bun add yargs

Overview

Quick Start

typescript

import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';
import fs from 'fs/promises';

const argv = yargs(hideBin(process.argv))
  .command(
    'deploy <environment>',
    'Deploy application to specified environment',
    (yargs) => {
      return yargs
        .positional('environment', {
          describe: 'Target environment',
          choices: ['staging', 'production'],
          type: 'string'
        })
        .option('dry-run', {
          alias: 'd',
          type: 'boolean',
          description: 'Simulate deployment without applying changes'
        })
        .option('version', {
          alias: 'v',
          type: 'string',
          demandOption: true,
          description: 'Version tag to deploy'
        });
    },
    async (argv) => {
      console.log(`Deploying v${argv.version} to ${argv.environment}`);
      if (argv.dryRun) {
        console.log('[DRY RUN] No changes applied');
        return;
      }
      await fs.writeFile(
        './deploy.log',
        `${new Date().toISOString()}: ${argv.environment}@${argv.version}\n`,
        { flag: 'a' }
      );
      console.log('Deployment complete');
    }
  )
  .option('config', {
    alias: 'c',
    type: 'string',
    description: 'Path to configuration file'
  })
  .demandCommand(1, 'You must provide a command')
  .strict()
  .help()
  .parse();

Use Cases

Pros & Cons

Pros

+Zero-effort help generation and shell completion scripts eliminate documentation boilerplate entirely
+Subcommand architecture with builder functions scales elegantly from simple scripts to complex multi-level CLIs
+Comprehensive validation (type coercion, required options, conflicts, implications) catches user errors before your code runs
+Mature ecosystem integration with plugin support via configuration extends and package.json loading
+Excellent TypeScript support with detailed type definitions for autocomplete and compile-time safety

Cons

−Heavier bundle size (compared to minimist/meow) adds ~200KB to dependencies, problematic for size-constrained environments
−Learning curve for advanced features like middleware, command modules, and strict mode configuration
−Automatic type coercion can cause surprising behavior (e.g., numeric strings converted unexpectedly) without explicit configuration
−Overkill for simple scripts that only need 2-3 flags; setup overhead outweighs benefits in trivial cases
−Error messages for misconfigured commands can be cryptic when chaining many validation rules together