@vexify-org/yaggs

A powerful CLI argument parser for Node.js, designed as a modern alternative to yargs.

Features

• Deprecation warnings for deprecated options
• Subcommand aliases
• Extended type validators (email, URL, UUID, etc.)
• Default value merge
• Conflict detection
• Exclusive groups
• Interactive prompts
• Zero dependencies

Installation

npm install @vexify-org/yaggs

Usage

Basic Example

const yaggs = require('@vexify-org/yaggs');

const argv = yaggs
    .option('name', {
        alias: 'n',
        type: 'string',
        description: 'Your name',
        default: 'World'
    })
    .option('count', {
        alias: 'c',
        type: 'number',
        description: 'Number of times to greet',
        default: 1
    })
    .argv;

console.log(`Hello, ${argv.name}!`.repeat(argv.count));

Commands

yaggs
    .command('start', 'Start MineP2P client', (y) => {
        y.option('room', {
            type: 'string',
            description: 'Room ID to join'
        });
    }, (argv) => {
        console.log('Starting...', argv.room);
    })
    .command('stop', 'Stop MineP2P client', null, () => {
        console.log('Stopping...');
    })
    .argv;

Note: use simple command names (start, not start [room]) and bind room-style inputs as options. To register a bare handler with no sub-command builder, pass null as the third argument (the builder) and your handler as the fourth.

Type Validators

yaggs
    .option('email', {
        type: 'email',
        description: 'Email address'
    })
    .option('url', {
        type: 'url',
        description: 'Website URL'
    })
    .option('uuid', {
        type: 'uuid',
        description: 'UUID'
    })
    .argv;

Deprecation Warnings

yaggs
    .option('old-flag', {
        type: 'boolean',
        deprecated: true,
        deprecatedMessage: 'Use --new-flag instead'
    })
    .argv;

Exclusive Groups

yaggs
    .option('json', {
        type: 'boolean',
        conflicts: 'yaml'
    })
    .option('yaml', {
        type: 'boolean',
        conflicts: 'json'
    })
    .argv;

API

• yaggs.option(name, options) - Define an option
• yaggs.command(cmd, desc, builder, handler) - Define a command
• yaggs.parse(args) - Parse arguments
• yaggs.argv - Get parsed arguments

Changelog

8.1.1 — bug fixes

• exitProcess: false is now honoured. Passing it as a constructor option (or via .exitProcess(false)) stops --help / --version from calling process.exit, so yaggs no longer kills the host when you embed it.
• Validation errors are non-fatal. _handleError no longer calls process.exit(1). Usage / validation failures are echoed to stderr and collected into result.error / result.errors for the caller to inspect.
• Middleware now runs exactly once in parseAsync() / run() (previously it ran twice).
• Negative numbers and flag-like strings work as option values (e.g. --count -5, --msg --weird), while a following known flag still terminates the previous option.
• env method unified. yaggs.env('KEY', 'value') sets a process env var, yaggs.env('KEY') reads one, and yaggs.env('<option>', '<VAR>') binds an option to an env var — the two overlapping definitions are now one.
• Environment fallback now applies when an option is absent and overrides config (CLI > env > config > defaults).
• Option names preserve case (apiKey stays result.apiKey).
• demandCommand() is now enforced and defaultHandler(fn) is a real method instead of a dead property.
• implies overrides a default value but never an explicit CLI value.
• Added .argv getter so yaggs.option(...).argv works as documented.

Compatibility

• Node.js >= 14.0.0
• Drop-in replacement for yargs in most cases

License

Apache-2.0 - Copyright (c) Vexify 2026