sindresorhus/meow


CLI app helper

License: MIT

Language: JavaScript

Keywords: cli, command-line, javascript, kitten, meow, nodejs


meow Build Status

CLI app helper

Features

  • Parses arguments
  • Converts flags to camelCase
  • 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, -r  Include a unicorn

	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'
		}
	}
});
/*
{
	flags: {rainbow: true, unicorn: false},

}
*/

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

Project Statistics

Sourcerank 19
Repository Size 642 KB
Stars 1,258
Forks 64
Watchers 16
Open issues 12
Dependencies 13
Contributors 18
Tags 16
Created
Last updated
Last pushed

Top Contributors See all

Sindre Sorhus Kevin Mårtensson Callum Locke Shinnosuke Watanabe Simen Bekkhus Eugene Sharygin Ian MacLeod Sam Verschueren Vadim Demedes Thiago Delgado Pinto mackie Pierre Vanduynslager Florian Breisch Angelo Ashmore Dimzel Sobolev Rouven Weßling Jamie Kyle James Talmage

Packages Referencing this Repo

meow
CLI app helper
Latest release 5.0.0 - Updated - 1.26K stars
org.webjars.npm:meow
WebJar for meow
Latest release 3.6.0 - Updated - 1.26K stars

Recent Tags See all

v5.0.0 April 25, 2018
v4.0.1 April 25, 2018
v4.0.0 November 26, 2017
v3.7.0 January 04, 2016
v3.6.0 November 15, 2015
v3.5.0 October 30, 2015
v3.4.2 October 07, 2015
v3.4.1 October 03, 2015
v3.4.0 October 03, 2015
3.3.0 June 18, 2015
v3.2.0 June 18, 2015
v3.1.0 February 26, 2015
v3.0.0 January 23, 2015
v2.1.0 January 08, 2015
v2.0.0 October 21, 2014

Interesting Forks See all

vadimdemedes/meow
CLI app helper
JavaScript - Last pushed - 1 stars
nwaltham/woofwoof
CLI app helper forked from the popular meow using nconf instead of mimimist
JavaScript - Other - Last pushed - 1 stars

Something wrong with this page? Make a suggestion

Last synced: 2018-04-25 04:45:58 UTC

Login to resync this repository