gem-hunter

CLI app helper

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

• 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
• Sets the process title to the binary name defined in package.json
• No dependencies!

npm install meow

./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);

Returns an object with:

• input (Array) - Non-flag arguments
• command (string | undefined) - The selected command when using commands
• flags (Object) - Flags converted to camelCase excluding aliases
• unnormalizedFlags (Object) - Flags converted to camelCase including aliases
• pkg (Object) - The package.json object
• help (string) - The help text used with --help
• showHelp([exitCode=2]) (Function) - Show the help text and exit with exitCode
• showVersion() (Function) - Show the version text and exit

Type: string

Shortcut for the help option.

Type: object

Required
Type: object

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

Type: object | string

Options for non-flag input arguments.

The value is an object with any of:

• type: Type of value. (Possible values: string boolean number array string-array boolean-array number-array)
• isRequired: Determine if at least one non-flag input argument is required. (Default: false)
  • If it's only known at runtime whether the input is required or not, you can pass a Function instead of a boolean, which based on the given input should decide if the input is required.
  • The first argument is the input string array, which contains the non-flag arguments.
  • The function should return a boolean, true if the input is required, otherwise false.

Example:

input: 'number'

Example:

input: {
	isRequired: true
}

Type: string[]

List of valid commands. Commands must be a single argument without whitespace and must not start with -.

When set, parsing stops at the first non-flag argument and treats it as the command. The remaining arguments are returned in input so they can be passed to a subcommand parser. An unknown command will show help and exit with code 2. Parent flags must appear before the command.

If no command is given, cli.command is undefined and meow does not exit — you decide what to do:

if (!cli.command) {
	cli.showHelp(); // or showHelp(0), or a custom message, or a default command
}

Example:

import meow from 'meow';

const cli = meow({
	importMeta: import.meta,
	commands: ['run', 'list'],
	flags: {
		verbose: {
			type: 'boolean',
			shortFlag: 'v'
		}
	}
});

if (!cli.command) {
	cli.showHelp(0);
}

if (cli.command === 'run') {
	const runCli = meow({importMeta: import.meta, argv: cli.input});
}

Type: object

Define argument flags.

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

• type: Type of value. (Possible values: string boolean number)
• choices: Limit valid values to a predefined set of choices.
• default: Default value when the flag is not specified.
• shortFlag: A short flag alias.
• aliases: Other names for the flag.
• isMultiple: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
  • Multiple values are provided by specifying the flag multiple times, for example, $ foo -u rainbow -u cat. Space- or comma-separated values are currently not supported.
• isRequired: Determine if the flag is required. (Default: false)
  • If it's only known at runtime whether the flag is required or not, you can pass a Function instead of a boolean, which based on the given flags and other non-flag arguments, should decide if the flag is required. Two arguments are passed to the function:
  • The first argument is the flags object, which contains the flags converted to camel-case excluding aliases.
  • The second argument is the input string array, which contains the non-flag arguments.
  • The function should return a boolean, true if the flag is required, otherwise false.

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;
		}
	}
}

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

Description to show above the help text.

Set it to false to disable it altogether.

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.

Type: string
Default: The package.json "version" property

Set a custom version output.

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 is only triggered when --help is the only argument.

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 is only triggered when --version is the only argument.

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.

Type: string[]
Default: process.argv.slice(2)

Custom arguments object.

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.

Also applies to flags without explicit types. By default, --count 42 remains as the string '42'. With inferType: true, it becomes the number 42.

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
	},
	…
}
*/

Type: boolean
Default: true

Whether to allow unknown flags or not.

Type: number
Default: 2

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

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…