0
# Meow
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: meow
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install meow`
10

11
## Core Imports
12

13
```javascript
14
import meow from 'meow';
15
```
16

17
Import with types for TypeScript:
18

19
```typescript  
20
import meow, { type Options, type Result, type FlagType } from 'meow';
21
```
22

23
For CommonJS:
24

25
```javascript
26
const meow = require('meow');
27
```
28

29
## Basic Usage
30

31
```javascript
32
#!/usr/bin/env node
33
import meow from 'meow';
34

35
const cli = meow(`
36
  Usage
37
    $ foo <input>
38

39
  Options
40
    --rainbow, -r  Include a rainbow
41

42
  Examples
43
    $ foo unicorns --rainbow
44
    🌈 unicorns 🌈
45
`, {
46
  importMeta: import.meta,
47
  flags: {
48
    rainbow: {
49
      type: 'boolean',
50
      shortFlag: 'r'
51
    }
52
  }
53
});
54

55
/*
56
{
57
  input: ['unicorns'],
58
  flags: {rainbow: true},
59
  unnormalizedFlags: {rainbow: true, r: true},
60
  pkg: {...},
61
  help: '...',
62
  showHelp: [Function],
63
  showVersion: [Function]
64
}
65
*/
66

67
console.log('Input:', cli.input);
68
console.log('Flags:', cli.flags);
69
```
70

71
## Capabilities
72

73
### CLI Parsing
74

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

77
```typescript { .api }
78
/**
79
 * Parse command-line arguments with help text and options
80
 * @param helpMessage - Help text to display with --help
81
 * @param options - Configuration options for parsing
82
 * @returns Parsed CLI result object
83
 */
84
function meow<Flags extends AnyFlags>(
85
  helpMessage: string, 
86
  options?: Options<Flags>
87
): Result<Flags>;
88

89
/**
90
 * Parse command-line arguments with options only
91
 * @param options - Configuration options for parsing
92
 * @returns Parsed CLI result object
93
 */
94
function meow<Flags extends AnyFlags>(options?: Options<Flags>): Result<Flags>;
95
```
96

97
### Flag Definition
98

99
Configure argument flags with various options and validation rules.
100

101
```typescript { .api }
102
interface Flag<PrimitiveType extends FlagType, Type, IsMultiple = false> {
103
  /** Type of value: 'string' | 'boolean' | 'number' */
104
  readonly type?: PrimitiveType;
105
  /** Limit valid values to predefined choices */
106
  readonly choices?: Type extends unknown[] ? Type : Type[];
107
  /** Default value when flag is not specified */
108
  readonly default?: Type;
109
  /** Single character alias for the flag */
110
  readonly shortFlag?: string;
111
  /** Alternative names for the flag */
112
  readonly aliases?: string[];
113
  /** Allow multiple values (creates array) */
114
  readonly isMultiple?: IsMultiple;
115
  /** Determine if flag is required (boolean or function) */
116
  readonly isRequired?: boolean | IsRequiredPredicate;
117
}
118
```
119

120
**Flag Usage Examples:**
121

122
```javascript
123
// String flag with choices and aliases
124
flags: {
125
  unicorn: {
126
    type: 'string',
127
    choices: ['rainbow', 'cat', 'unicorn'],
128
    default: 'rainbow',
129
    shortFlag: 'u',
130
    aliases: ['unicorns']
131
  }
132
}
133

134
// Multiple boolean flag
135
flags: {
136
  verbose: {
137
    type: 'boolean',
138
    isMultiple: true,
139
    shortFlag: 'v'
140
  }
141
}
142

143
// Required flag with dynamic requirement
144
flags: {
145
  output: {
146
    type: 'string',
147
    isRequired: (flags, input) => {
148
      return flags.format === 'file';
149
    }
150
  }
151
}
152
```
153

154
### Configuration Options
155

156
Configure parsing behavior, help text, and validation rules.
157

158
```typescript { .api }
159
interface Options<Flags extends AnyFlags> {
160
  /** Required import.meta object for package.json discovery */
161
  readonly importMeta: ImportMeta;
162
  /** Flag definitions object */
163
  readonly flags?: Flags;
164
  /** Description shown above help text (default: package.json description) */
165
  readonly description?: string | false;
166
  /** Help text content (supports template literals) */
167
  readonly help?: string | false;
168
  /** Version string override (default: package.json version) */
169
  readonly version?: string | false;
170
  /** Automatically show help on --help flag */
171
  readonly autoHelp?: boolean;
172
  /** Automatically show version on --version flag */
173
  readonly autoVersion?: boolean;
174
  /** Custom package.json object */
175
  readonly pkg?: Record<string, unknown>;
176
  /** Custom arguments array (default: process.argv.slice(2)) */
177
  readonly argv?: readonly string[];
178
  /** Auto-infer argument types from values */
179
  readonly inferType?: boolean;
180
  /** Default value for undefined boolean flags */
181
  readonly booleanDefault?: boolean | null | undefined;
182
  /** Allow unknown flags (default: true) */
183
  readonly allowUnknownFlags?: boolean;
184
  /** Allow parent flags (default: true) */
185
  readonly allowParentFlags?: boolean;
186
  /** Number of spaces for help text indentation (default: 2) */
187
  readonly helpIndent?: number;
188
  /** @deprecated Hard rejection for unhandled promises */
189
  readonly hardRejection?: boolean;
190
}
191
```
192

193
### Result Object
194

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

197
```typescript { .api }
198
interface Result<Flags extends AnyFlags> {
199
  /** Non-flag arguments array */
200
  input: string[];
201
  /** Flags converted to camelCase excluding aliases */
202
  flags: CamelCasedProperties<TypedFlags<Flags>> & Record<string, unknown>;
203
  /** Flags converted to camelCase including aliases */
204
  unnormalizedFlags: TypedFlags<Flags> & Record<string, unknown>;
205
  /** The package.json object */
206
  pkg: PackageJson;
207
  /** Formatted help text */
208
  help: string;
209
  /** Show help text and exit with code (default: 2) */
210
  showHelp: (exitCode?: number) => never;
211
  /** Show version text and exit */
212
  showVersion: () => void;
213
}
214
```
215

216
## Types
217

218
All TypeScript type definitions for comprehensive type safety.
219

220
```typescript { .api }
221
/** Supported flag value types */
222
type FlagType = 'string' | 'boolean' | 'number';
223

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

230
/** Type-safe flags object with proper inference based on flag definitions */
231
type TypedFlags<Flags extends Record<string, any>> = {
232
  [F in keyof Flags]: Flags[F] extends {isMultiple: true}
233
    ? Flags[F] extends {type: 'string'}
234
      ? string[]
235
      : Flags[F] extends {type: 'number'}
236
        ? number[]
237
        : Flags[F] extends {type: 'boolean'}
238
          ? boolean[]
239
          : unknown[]
240
    : Flags[F] extends {type: 'string'}
241
      ? string
242
      : Flags[F] extends {type: 'number'}
243
        ? number
244
        : Flags[F] extends {type: 'boolean'}
245
          ? boolean
246
          : unknown
247
};
248
```
249

250
## Key Features
251

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

260
### Flag Types and Validation
261
- **String flags**: Accept string values with optional choices validation
262
- **Boolean flags**: Support true/false with negation and default values
263
- **Number flags**: Accept numeric values with automatic conversion
264
- **Multiple flags**: Accept arrays via repeated flag usage (--flag value1 --flag value2)
265
- **Required flags**: Static or dynamic requirement validation
266
- **Aliases**: Support short flags and alternative names
267

268
### Help and Version
269
- **Auto-help**: Automatic help generation from help text and flag definitions
270
- **Auto-version**: Automatic version display from package.json
271
- **Custom help**: Support for custom help text with template literals
272
- **Help formatting**: Configurable indentation and automatic text trimming
273

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

283
**Error Examples:**
284

285
```javascript
286
// Unknown flag error
287
$ my-cli --unknown-flag
288
// Output: Unknown flag --unknown-flag
289
// Process exits with code 2
290

291
// Missing required flag
292
flags: {
293
  output: {
294
    type: 'string',
295
    isRequired: true
296
  }
297
}
298
$ my-cli
299
// Output: Missing required flag --output
300
// Process exits with code 2
301

302
// Invalid choice error
303
flags: {
304
  format: {
305
    type: 'string',
306
    choices: ['json', 'yaml', 'xml']
307
  }
308
}
309
$ my-cli --format csv
310
// Output: Unknown value for flag --format: csv. Value must be one of: [json, yaml, xml]
311
// Process exits with code 2
312
```
313

314
**Advanced Configuration Example:**
315

316
```javascript
317
import meow from 'meow';
318

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

326
    Commands
327
      build     Build the project
328
      test      Run tests
329

330
    Options
331
      --config, -c    Configuration file path
332
      --verbose, -v   Enable verbose output (can be used multiple times)
333
      --dry-run       Show what would be done without executing
334
      --no-cache      Disable caching
335
  `,
336
  flags: {
337
    config: {
338
      type: 'string',
339
      shortFlag: 'c',
340
      default: './config.json'
341
    },
342
    verbose: {
343
      type: 'boolean',
344
      shortFlag: 'v',
345
      isMultiple: true
346
    },
347
    dryRun: {
348
      type: 'boolean',
349
      default: false
350
    },
351
    cache: {
352
      type: 'boolean',
353
      default: true
354
    }
355
  },
356
  booleanDefault: undefined,
357
  allowUnknownFlags: false,
358
  helpIndent: 4
359
});
360

361
// Advanced booleanDefault behavior example
362
const cli2 = meow({
363
  importMeta: import.meta,
364
  booleanDefault: undefined, // Exclude undefined boolean flags from result
365
  flags: {
366
    rainbow: {
367
      type: 'boolean',
368
      default: true,     // This takes precedence over booleanDefault
369
      shortFlag: 'r'
370
    },
371
    unicorn: {
372
      type: 'boolean',
373
      default: false,    // This takes precedence over booleanDefault
374
      shortFlag: 'u'
375
    },
376
    sparkles: {
377
      type: 'boolean'    // Will be excluded if not provided
378
    }
379
  }
380
});
381

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