meow

CLI app helper

Features

• Parses arguments
• Converts flags to camelCase
• Negates flags when using the --no- prefix
• Outputs version when --version
• Outputs description and supplied help text when --help
• Makes unhandled rejected promises fail loudly instead of the default silent fail
• Sets the process title to the binary name defined in package.json

Install

$ npm install meow

Usage

$ ./foo-app.js unicorns --rainbow

#!/usr/bin/env node
'use strict';
const meow = require('meow');
const foo = require('.');

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

	Options
	  --rainbow, -r  Include a rainbow

	Examples
	  $ foo unicorns --rainbow
	  🌈 unicorns 🌈
`, {
	flags: {
		rainbow: {
			type: 'boolean',
			alias: 'r'
		}
	}
});
/*
{
	input: ['unicorns'],
	flags: {rainbow: true},
	...
}
*/

foo(cli.input[0], cli.flags);

API

meow(options, [minimistOptions])

Returns an Object with:

• input (Array) - Non-flag arguments
• flags (Object) - Flags converted to camelCase
• pkg (Object) - The package.json object
• help (string) - The help text used with --help
• showHelp([code=2]) (Function) - Show the help text and exit with code
• showVersion() (Function) - Show the version text and exit

options

Type: Object Array string

Can either be a string/array that is the help or an options object.

flags

Type: Object

Define argument flags.

The key is the flag name and the value is an object with any of:

• type: Type of value. (Possible values: string boolean)
• alias: Usually used to define a short flag alias.
• default: Default value when the flag is not specified.

Example:

flags: {
	unicorn: {
		type: 'string',
		alias: 'u',
		default: 'rainbow'
	}
}

description

Type: string boolean

Default: The package.json "description" property

Description to show above the help text.

Set it to false to disable it altogether.

help

Type: string boolean

The help text you want shown.

The input is reindented and starting/ending newlines are trimmed which means you can use a template literal without having to care about using the correct amount of indent.

The description will be shown above your help text automatically.

version

Type: string boolean

Default: The package.json "version" property

Set a custom version output.

autoHelp

Type: boolean

Default: true

Automatically show the help text when the --help flag is present. Useful to set this value to false when a CLI manages child CLIs with their own help text.

autoVersion

Type: boolean

Default: true

Automatically show the version text when the --version flag is present. Useful to set this value to false when a CLI manages child CLIs with their own version text.

pkg

Type: Object

Default: Closest package.json upwards

package.json as an Object.

You most likely don’t need this option.

argv

Type: Array

Default: process.argv.slice(2)

Custom arguments object.

inferType

Type: boolean

Default: false

Infer the argument type.

By default, the argument 5 in $ foo 5 becomes a string. Enabling this would infer it as a number.

booleanDefault

Type: boolean null undefined

Default: false

Value of boolean flags not defined in argv.
If set to undefined the flags not defined in argv will be excluded from the result.
The default value set in boolean flags take precedence over booleanDefault.

Example:

const cli = meow(`
	Usage
	  $ foo

	Options
	  --rainbow, -r  Include a rainbow
	  --unicorn, -u  Include a unicorn
	  --no-sparkles  Exclude sparkles

	Examples
	  $ foo
	  🌈 unicorns✨🌈
`, {
	booleanDefault: undefined,
	flags: {
		rainbow: {
			type: 'boolean',
			default: true,
			alias: 'r'
		},
		unicorn: {
			type: 'boolean',
			default: false,
			alias: 'u'
		},
		cake: {
			type: 'boolean',
			alias: 'c'
		},
		sparkles: {
			type: 'boolean',
			default: true
		}
	}
});
/*
{
	flags: {
		rainbow: true,
		r: true,
		unicorn: false,
		u: false,
		sparkles: true
	},
	…
}
*/

Promises

Meow will make unhandled rejected promises fail loudly instead of the default silent fail. Meaning you don’t have to manually .catch() promises used in your CLI.

Tips

See chalk if you want to colorize the terminal output.

See get-stdin if you want to accept input from stdin.

See conf if you need to persist some data.

See update-notifier if you want update notifications.

More useful CLI utilities…

License

MIT © Sindre Sorhus