meow

CLI app helper

weekly downloads30.3M

versionv14.0.0

licenseMIT

categorytoolchain

clibinutilutilityhelperargvcommandlinemeowcatkittenparseroptionflagsinputcmdconsole

Overview

meow is a lightweight CLI argument parser for Node.js that simplifies building command-line applications. It handles the repetitive tasks of parsing command-line flags, generating help text, and managing version output with minimal configuration. Built on top of minimist, meow automatically converts flags to camelCase and provides a declarative API for defining flag types, aliases, and defaults.

With over 30 million weekly downloads, meow powers CLI tools across the JavaScript ecosystem. It's maintained by Sindre Sorhus and follows a philosophy of being unopinionated and composable—providing essential functionality without forcing specific patterns or architectures. The library is ESM-only as of recent versions, embracing modern JavaScript standards.

meow excels in scenarios where you need a quick, type-safe CLI parser without the overhead of full-featured frameworks. It automatically generates formatted help output from your usage strings, handles --help and --version flags out of the box, and provides strong TypeScript inference from your flag definitions. The library is intentionally minimal, making it ideal for single-command CLIs, utility scripts, and tools where you want full control over the user experience without wrestling with opinionated abstractions.

Quick Start

typescript

#!/usr/bin/env node
import meow from 'meow';
import fs from 'node:fs';
import path from 'node:path';

const cli = meow(`
  Usage
    $ deploy <environment>

  Options
    --config, -c   Config file path
    --dry-run, -d  Preview changes without deploying
    --verbose, -v  Show detailed output

  Examples
    $ deploy production --config=./config.json
    $ deploy staging --dry-run
`, {
  importMeta: import.meta,
  flags: {
    config: {
      type: 'string',
      shortFlag: 'c',
      default: './deploy.config.json'
    },
    dryRun: {
      type: 'boolean',
      shortFlag: 'd',
      default: false
    },
    verbose: {
      type: 'boolean',
      shortFlag: 'v',
      default: false
    }
  }
});

const [environment] = cli.input;

if (!environment) {
  console.error('Error: environment is required');
  cli.showHelp();
}

if (!['staging', 'production'].includes(environment)) {
  console.error(`Error: invalid environment "${environment}"`);
  process.exit(1);
}

const configPath = path.resolve(cli.flags.config);

if (!fs.existsSync(configPath)) {
  console.error(`Error: config file not found at ${configPath}`);
  process.exit(1);
}

if (cli.flags.verbose) {
  console.log(`Environment: ${environment}`);
  console.log(`Config: ${configPath}`);
  console.log(`Dry run: ${cli.flags.dryRun}`);
}

if (cli.flags.dryRun) {
  console.log(`Would deploy to ${environment} (dry run mode)`);
} else {
  console.log(`Deploying to ${environment}...`);
}

Use Cases

Build utility scripts and automation tools: Create internal development scripts that need to accept configuration flags, file paths, or operational modes. meow handles argument parsing so you can focus on business logic without writing custom argv parsing code.

Develop npm package binaries: When publishing npm packages that include executable commands, meow provides the parsing layer for user-facing CLIs. It automatically reads package.json for version information and generates professional help output with minimal setup.

Prototype CLI applications quickly: During early development of command-line tools, meow lets you define flags declaratively and iterate rapidly. The automatic help generation means documentation stays in sync with your flag definitions without manual maintenance.

Create deployment and CI/CD scripts: Build custom deployment tools or continuous integration scripts that accept environment flags, configuration options, and operational parameters. meow's simple API keeps these scripts maintainable and self-documenting.

Wrap existing tools with custom interfaces: Build thin CLI wrappers around other tools or APIs where you need custom argument handling but don't want framework overhead. meow provides just enough structure without dictating application architecture.

Pros & Cons

Pros

+Minimal dependencies and small bundle size make it fast and lightweight for simple CLIs
+Strong TypeScript inference automatically derives flag types from definitions without manual type annotations
+Automatic help and version output generation reduces boilerplate and keeps documentation in sync with code
+Declarative flag API is more readable and maintainable than imperative parsing code
+CamelCase conversion of flags follows JavaScript conventions automatically

Cons

−No built-in support for subcommands requires external packages or custom implementation for multi-command CLIs
−ESM-only from version 9+ means no CommonJS support for older projects without module compatibility
−Limited built-in validation compared to frameworks like yargs means you write custom validation logic for complex requirements
−Minimal abstraction means you handle routing, command orchestration, and complex flag dependencies yourself
−Less opinionated structure can lead to inconsistent patterns across different projects without team conventions

Alternatives

commanderv14.0.3

the complete solution for node.js command-line programs

toolchaincommandercommand

275.9M / week

yargsv18.0.0

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

toolchainargumentargs

145.0M / week

Comparisons

commander vs meow

toolchain

Install

bash

npm install meow

bash

pnpm add meow

bash

bun add meow

Overview

Quick Start

typescript

#!/usr/bin/env node
import meow from 'meow';
import fs from 'node:fs';
import path from 'node:path';

const cli = meow(`
  Usage
    $ deploy <environment>

  Options
    --config, -c   Config file path
    --dry-run, -d  Preview changes without deploying
    --verbose, -v  Show detailed output

  Examples
    $ deploy production --config=./config.json
    $ deploy staging --dry-run
`, {
  importMeta: import.meta,
  flags: {
    config: {
      type: 'string',
      shortFlag: 'c',
      default: './deploy.config.json'
    },
    dryRun: {
      type: 'boolean',
      shortFlag: 'd',
      default: false
    },
    verbose: {
      type: 'boolean',
      shortFlag: 'v',
      default: false
    }
  }
});

const [environment] = cli.input;

if (!environment) {
  console.error('Error: environment is required');
  cli.showHelp();
}

if (!['staging', 'production'].includes(environment)) {
  console.error(`Error: invalid environment "${environment}"`);
  process.exit(1);
}

const configPath = path.resolve(cli.flags.config);

if (!fs.existsSync(configPath)) {
  console.error(`Error: config file not found at ${configPath}`);
  process.exit(1);
}

if (cli.flags.verbose) {
  console.log(`Environment: ${environment}`);
  console.log(`Config: ${configPath}`);
  console.log(`Dry run: ${cli.flags.dryRun}`);
}

if (cli.flags.dryRun) {
  console.log(`Would deploy to ${environment} (dry run mode)`);
} else {
  console.log(`Deploying to ${environment}...`);
}

Use Cases

Pros & Cons

Pros

+Minimal dependencies and small bundle size make it fast and lightweight for simple CLIs
+Strong TypeScript inference automatically derives flag types from definitions without manual type annotations
+Automatic help and version output generation reduces boilerplate and keeps documentation in sync with code
+Declarative flag API is more readable and maintainable than imperative parsing code
+CamelCase conversion of flags follows JavaScript conventions automatically

Cons

−No built-in support for subcommands requires external packages or custom implementation for multi-command CLIs
−ESM-only from version 9+ means no CommonJS support for older projects without module compatibility
−Limited built-in validation compared to frameworks like yargs means you write custom validation logic for complex requirements
−Minimal abstraction means you handle routing, command orchestration, and complex flag dependencies yourself
−Less opinionated structure can lead to inconsistent patterns across different projects without team conventions