or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-meow

CLI app helper that simplifies building command-line interfaces in Node.js with automatic argument parsing and flag handling

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/meow@13.2.x

To install, run

npx @tessl/cli install tessl/npm-meow@13.2.0

Meow

Meow is a CLI app helper that simplifies building command-line interfaces in Node.js. It automatically parses command-line arguments and flags, converts flags to camelCase format, provides built-in support for version and help text output, handles flag negation with --no- prefix, and includes advanced features like flag validation, multiple value support, and required flag detection.

Package Information

Package Name: meow
Package Type: npm
Language: TypeScript
Installation: npm install meow

Core Imports

import meow from 'meow';

Import with types for TypeScript:

import meow, { type Options, type Result, type FlagType } from 'meow';

For CommonJS:

const meow = require('meow');

Basic Usage

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

const cli = meow(`
  Usage
    $ foo <input>

  Options
    --rainbow, -r  Include a rainbow

  Examples
    $ foo unicorns --rainbow
    🌈 unicorns 🌈
`, {
  importMeta: import.meta,
  flags: {
    rainbow: {
      type: 'boolean',
      shortFlag: 'r'
    }
  }
});

/*
{
  input: ['unicorns'],
  flags: {rainbow: true},
  unnormalizedFlags: {rainbow: true, r: true},
  pkg: {...},
  help: '...',
  showHelp: [Function],
  showVersion: [Function]
}
*/

console.log('Input:', cli.input);
console.log('Flags:', cli.flags);

Capabilities

CLI Parsing

Main function that processes command-line arguments and returns a parsed result object.

/**
 * Parse command-line arguments with help text and options
 * @param helpMessage - Help text to display with --help
 * @param options - Configuration options for parsing
 * @returns Parsed CLI result object
 */
function meow<Flags extends AnyFlags>(
  helpMessage: string, 
  options?: Options<Flags>
): Result<Flags>;

/**
 * Parse command-line arguments with options only
 * @param options - Configuration options for parsing
 * @returns Parsed CLI result object
 */
function meow<Flags extends AnyFlags>(options?: Options<Flags>): Result<Flags>;

Flag Definition

Configure argument flags with various options and validation rules.

interface Flag<PrimitiveType extends FlagType, Type, IsMultiple = false> {
  /** Type of value: 'string' | 'boolean' | 'number' */
  readonly type?: PrimitiveType;
  /** Limit valid values to predefined choices */
  readonly choices?: Type extends unknown[] ? Type : Type[];
  /** Default value when flag is not specified */
  readonly default?: Type;
  /** Single character alias for the flag */
  readonly shortFlag?: string;
  /** Alternative names for the flag */
  readonly aliases?: string[];
  /** Allow multiple values (creates array) */
  readonly isMultiple?: IsMultiple;
  /** Determine if flag is required (boolean or function) */
  readonly isRequired?: boolean | IsRequiredPredicate;
}

Flag Usage Examples:

// String flag with choices and aliases
flags: {
  unicorn: {
    type: 'string',
    choices: ['rainbow', 'cat', 'unicorn'],
    default: 'rainbow',
    shortFlag: 'u',
    aliases: ['unicorns']
  }
}

// Multiple boolean flag
flags: {
  verbose: {
    type: 'boolean',
    isMultiple: true,
    shortFlag: 'v'
  }
}

// Required flag with dynamic requirement
flags: {
  output: {
    type: 'string',
    isRequired: (flags, input) => {
      return flags.format === 'file';
    }
  }
}

Configuration Options

Configure parsing behavior, help text, and validation rules.

interface Options<Flags extends AnyFlags> {
  /** Required import.meta object for package.json discovery */
  readonly importMeta: ImportMeta;
  /** Flag definitions object */
  readonly flags?: Flags;
  /** Description shown above help text (default: package.json description) */
  readonly description?: string | false;
  /** Help text content (supports template literals) */
  readonly help?: string | false;
  /** Version string override (default: package.json version) */
  readonly version?: string | false;
  /** Automatically show help on --help flag */
  readonly autoHelp?: boolean;
  /** Automatically show version on --version flag */
  readonly autoVersion?: boolean;
  /** Custom package.json object */
  readonly pkg?: Record<string, unknown>;
  /** Custom arguments array (default: process.argv.slice(2)) */
  readonly argv?: readonly string[];
  /** Auto-infer argument types from values */
  readonly inferType?: boolean;
  /** Default value for undefined boolean flags */
  readonly booleanDefault?: boolean | null | undefined;
  /** Allow unknown flags (default: true) */
  readonly allowUnknownFlags?: boolean;
  /** Allow parent flags (default: true) */
  readonly allowParentFlags?: boolean;
  /** Number of spaces for help text indentation (default: 2) */
  readonly helpIndent?: number;
  /** @deprecated Hard rejection for unhandled promises */
  readonly hardRejection?: boolean;
}

Result Object

The parsed CLI result with input, flags, and utility functions.

interface Result<Flags extends AnyFlags> {
  /** Non-flag arguments array */
  input: string[];
  /** Flags converted to camelCase excluding aliases */
  flags: CamelCasedProperties<TypedFlags<Flags>> & Record<string, unknown>;
  /** Flags converted to camelCase including aliases */
  unnormalizedFlags: TypedFlags<Flags> & Record<string, unknown>;
  /** The package.json object */
  pkg: PackageJson;
  /** Formatted help text */
  help: string;
  /** Show help text and exit with code (default: 2) */
  showHelp: (exitCode?: number) => never;
  /** Show version text and exit */
  showVersion: () => void;
}

Types

All TypeScript type definitions for comprehensive type safety.

/** Supported flag value types */
type FlagType = 'string' | 'boolean' | 'number';

/** Callback function to determine if a flag is required during runtime */
type IsRequiredPredicate = (
  flags: Readonly<Record<string, any>>, 
  input: readonly string[]
) => boolean;

/** Type-safe flags object with proper inference based on flag definitions */
type TypedFlags<Flags extends Record<string, any>> = {
  [F in keyof Flags]: Flags[F] extends {isMultiple: true}
    ? Flags[F] extends {type: 'string'}
      ? string[]
      : Flags[F] extends {type: 'number'}
        ? number[]
        : Flags[F] extends {type: 'boolean'}
          ? boolean[]
          : unknown[]
    : Flags[F] extends {type: 'string'}
      ? string
      : Flags[F] extends {type: 'number'}
        ? number
        : Flags[F] extends {type: 'boolean'}
          ? boolean
          : unknown
};

Key Features

Argument Processing

Automatic parsing: Uses yargs-parser for robust argument processing
camelCase conversion: Flag names automatically converted from kebab-case to camelCase
Flag negation: Support for --no- prefix to negate boolean flags (e.g., --no-cache sets cache: false)
Type inference: Optional automatic type inference for arguments
Process title: Automatically sets process title from package.json bin property or package name
Promise handling: Makes unhandled rejected promises fail hard instead of silent fail

Flag Types and Validation

String flags: Accept string values with optional choices validation
Boolean flags: Support true/false with negation and default values
Number flags: Accept numeric values with automatic conversion
Multiple flags: Accept arrays via repeated flag usage (--flag value1 --flag value2)
Required flags: Static or dynamic requirement validation
Aliases: Support short flags and alternative names

Help and Version

Auto-help: Automatic help generation from help text and flag definitions
Auto-version: Automatic version display from package.json
Custom help: Support for custom help text with template literals
Help formatting: Configurable indentation and automatic text trimming

Error Handling

Validation errors: Detailed error reporting for invalid flag values with specific error messages
Unknown flags: Optional validation and reporting of unrecognized flags (exits with code 2)
Required flags: Missing required flag validation with helpful error messages
Choice validation: Validates flag values against predefined choices with clear error reporting
Multiple flag validation: Prevents setting single-value flags multiple times
Promise rejection: Makes unhandled rejected promises fail hard instead of silent fail
Process exit: Automatic process exit on validation failures (code 2) and help/version display (code 0)

Error Examples:

// Unknown flag error
$ my-cli --unknown-flag
// Output: Unknown flag --unknown-flag
// Process exits with code 2

// Missing required flag
flags: {
  output: {
    type: 'string',
    isRequired: true
  }
}
$ my-cli
// Output: Missing required flag --output
// Process exits with code 2

// Invalid choice error
flags: {
  format: {
    type: 'string',
    choices: ['json', 'yaml', 'xml']
  }
}
$ my-cli --format csv
// Output: Unknown value for flag --format: csv. Value must be one of: [json, yaml, xml]
// Process exits with code 2

Advanced Configuration Example:

import meow from 'meow';

const cli = meow({
  importMeta: import.meta,
  description: 'My awesome CLI tool',
  help: `
    Usage
      $ my-tool <command> [options]

    Commands
      build     Build the project
      test      Run tests

    Options
      --config, -c    Configuration file path
      --verbose, -v   Enable verbose output (can be used multiple times)
      --dry-run       Show what would be done without executing
      --no-cache      Disable caching
  `,
  flags: {
    config: {
      type: 'string',
      shortFlag: 'c',
      default: './config.json'
    },
    verbose: {
      type: 'boolean',
      shortFlag: 'v',
      isMultiple: true
    },
    dryRun: {
      type: 'boolean',
      default: false
    },
    cache: {
      type: 'boolean',
      default: true
    }
  },
  booleanDefault: undefined,
  allowUnknownFlags: false,
  helpIndent: 4
});

// Advanced booleanDefault behavior example
const cli2 = meow({
  importMeta: import.meta,
  booleanDefault: undefined, // Exclude undefined boolean flags from result
  flags: {
    rainbow: {
      type: 'boolean',
      default: true,     // This takes precedence over booleanDefault
      shortFlag: 'r'
    },
    unicorn: {
      type: 'boolean',
      default: false,    // This takes precedence over booleanDefault
      shortFlag: 'u'
    },
    sparkles: {
      type: 'boolean'    // Will be excluded if not provided
    }
  }
});

// $ my-cli --rainbow
// Result: { flags: { rainbow: true, unicorn: false } }
// Note: sparkles is excluded since it wasn't provided and booleanDefault is undefined