🌜
🌞
meow

meow

v10.1.3

CLI app helper

npm install meow

README

meow

CLI app helper

meow

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

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 hard 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
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,
    flags: {
        rainbow: {
            type: 'boolean',
            alias: 'r'
        }
    }
});
/*
{
    input: ['unicorns'],
    flags: {rainbow: true},
    ...
}
*/

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

API

meow(helpText, options?)

meow(options)

Returns an object with:

  • input (Array) - Non-flag arguments
  • 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

helpText

Type: string

Shortcut for the help option.

options

Type: object

importMeta

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:

  • type: Type of value. (Possible values: string boolean number)
  • alias: Usually used to define a short flag alias.
  • default: Default value when the flag is not specified.
  • 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.
  • 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.

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',
        alias: 'u',
        default: ['rainbow', 'cat'],
        isMultiple: true,
        isRequired: (flags, input) => {
            if (flags.otherFlag) {
                return true;
            }

            return false;
        }
    }
}
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.

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.

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

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,
            alias: 'r'
        },
        unicorn: {
            type: 'boolean',
            default: false,
            alias: 'u'
        },
        cake: {
            type: 'boolean',
            alias: 'c'
        },
        sparkles: {
            type: 'boolean',
            default: true
        }
    }
});
/*
{
    flags: {
        rainbow: true,
        unicorn: false,
        sparkles: true
    },
    unnormalizedFlags: {
        rainbow: true,
        r: true,
        unicorn: false,
        u: false,
        sparkles: true
    },
    …
}
*/
hardRejection

Type: boolean
Default: true

Whether to use hard-rejection or not. Disabling this can be useful if you need to handle process.on('unhandledRejection') yourself.

allowUnknownFlags

Type boolean
Default: true

Whether to allow unknown flags or not.

Promises

Meow will make unhandled rejected promises fail hard 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…


Get professional support for this package with a Tidelift subscription
Tidelift helps make open source sustainable for maintainers while giving companies
assurances about security, maintenance, and licensing for their dependencies.

Release Notes

10.1.3
By Sindre Sorhus • Published on June 21, 2022
  • Fix return type for .showHelp() (#213) db55316

https://github.com/sindresorhus/meow/compare/v10.1.2...v10.1.3

10.1.2
By Sindre Sorhus • Published on November 21, 2021
10.1.1
By Sindre Sorhus • Published on July 29, 2021
  • Fix failure with isMultiple when isRequired function returns false (#194) e1f0e24

https://github.com/sindresorhus/meow/compare/v10.1.0...v10.1.1

10.1.0
By Sindre Sorhus • Published on July 15, 2021
  • Upgrade dependencies 829aab0
  • Allow default property of Flag types to accept arrays (#190) ae73466

https://github.com/sindresorhus/meow/compare/v10.0.1...v10.1.0

10.0.1
By Sindre Sorhus • Published on June 8, 2021
10.0.0
By Sindre Sorhus • Published on May 5, 2021

Breaking

  • Require Node.js 12 (#181) 05320ac
  • This package is now pure ESM. Please read this.
  • You must now pass in the importMeta option so meow can find your package.json:
 const cli = meow(…, {
+    importMeta: import.meta
 });

Previously, meow used some tricks to infer the location of your package.json, but this no longer works in ESM.

https://github.com/sindresorhus/meow/compare/v9.0.0...v10.0.0

9.0.0
By Sindre Sorhus • Published on January 7, 2021

Breaking

  • Strictly validate flag config (#168) 1609709 This is a breaking change if you incorrectly used kebab-case format for flags (was never officially supported) in the meow config:
 meow(``, {
     flags: {
-        'foo-bar': {
+        fooBar: {
             type: 'boolean'
         }
     }
 });

https://github.com/sindresorhus/meow/compare/v8.1.0...v9.0.0

8.1.1
By Sindre Sorhus • Published on January 7, 2021
  • Fix reporting missing required flags (#168) 1609709

https://github.com/sindresorhus/meow/compare/v8.1.0...v8.1.1

8.1.0
By Sindre Sorhus • Published on December 25, 2020
8.0.0
By Sindre Sorhus • Published on October 28, 2020

Breaking

  • Default isMultiple option to empty array (#163) 14924de
  • Make isMultiple option non-greedy (#162) 49ce74d

Fixes

  • Gracefully handle package.json not being found (#167) ef7ae5d

https://github.com/sindresorhus/meow/compare/v7.1.1...v8.0.0

General

License
MIT
Typescript Types
Built-in
Tree-shakeable
Yes

Popularity

GitHub Stargazers
3,045
Community Interest
2,969
Number of Forks
148

Maintenance

Commits
10/219/2202
Last Commit
Open Issues
26
Closed Issues
90
Open Pull Requests
2
Closed Pull Requests
41

Versions

Versions Released
10/219/2201
Latest Version Released
Jun 21, 2022
Current Tags
latest10.1.3

Contributors

sindresorhus
sindresorhus
Commits: 91
ulken
ulken
Commits: 9
LitoMore
LitoMore
Commits: 4
kevva
kevva
Commits: 3
BendingBender
BendingBender
Commits: 2
shinnn
shinnn
Commits: 2
callumlocke
callumlocke
Commits: 2
pvdlg
pvdlg
Commits: 1
voxpelli
voxpelli
Commits: 1
jakejarvis
jakejarvis
Commits: 1
sbencoding
sbencoding
Commits: 1
weareoutman
weareoutman
Commits: 1
coreyfarrell
coreyfarrell
Commits: 1
angeloashmore
angeloashmore
Commits: 1
macklinu
macklinu
Commits: 1