Home

Awesome

meow

CLI app helper

I would recommend reading this guide on how to make user-friendly command-line tools.

Features

Install

npm install meow

Usage

./foo-app.js unicorns --rainbow

#!/usr/bin/env node
import meow from 'meow';
import foo from './lib/index.js';

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

	Options
	  --rainbow, -r  Include a rainbow

	Examples
	  $ foo unicorns --rainbow
	  🌈 unicorns 🌈
`, {
	importMeta: import.meta, // This is required
	flags: {
		rainbow: {
			type: 'boolean',
			shortFlag: 'r'
		}
	}
});
/*
{
	input: ['unicorns'],
	flags: {rainbow: true},
	...
}
*/

foo(cli.input.at(0), cli.flags);

API

meow(helpText, options)

meow(options)

Returns an object with:

helpText

Type: string

Shortcut for the help option.

options

Type: object

importMeta

Required
Type: object

Pass in import.meta. This is used to find the correct package.json file.

flags

Type: object

Define argument flags.

The key is the flag name in camel-case and the value is an object with any of:

Note that flags are always defined using a camel-case key (myKey), but will match arguments in kebab-case (--my-key).

Example:

flags: {
	unicorn: {
		type: 'string',
		choices: ['rainbow', 'cat', 'unicorn'],
		default: ['rainbow', 'cat'],
		shortFlag: 'u',
		aliases: ['unicorns'],
		isMultiple: true,
		isRequired: (flags, input) => {
			if (flags.otherFlag) {
				return true;
			}

			return false;
		}
	}
}
description

Type: string | false
Default: The package.json "description" property

Description to show above the help text.

Set it to false to disable it altogether.

help

Type: string | false

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.

Set it to false to disable it altogether.

version

Type: string
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.

This option is only considered when there is only one argument in process.argv.

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.

This option is only considered when there is only one argument in process.argv.

pkg

Type: object
Default: Closest package.json upwards

package.json as an object.

Note: Setting this stops meow from finding a package.json.

You most likely don't need this option.

argv

Type: string[]
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 | 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.

Note: If used in conjunction with isMultiple, the default flag value is set to [].

Caution: Explicitly specifying undefined for booleanDefault has different meaning from omitting key itself.

Example:

import meow from 'meow';

const cli = meow(`
	Usage
	  $ foo

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

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

Type boolean
Default: true

Whether to allow unknown flags or not.

helpIndent

Type number
Default: 2

The number of spaces to use for indenting the help text.

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.

More useful CLI utilities…