meow

  • Version 10.1.1
  • Published
  • 24.8 kB
  • 12 dependencies
  • MIT license

Install

npm i meow
yarn add meow
pnpm add meow

Overview

CLI app helper

Index

Functions

function meow

meow: {
<Flags extends AnyFlags>(
helpMessage: string,
options?: Options<Flags>
): Result<Flags>;
<Flags extends AnyFlags>(options?: Options<Flags>): Result<Flags>;
};
  • Parameter helpMessage

    Shortcut for the help option.

    Example 1

    #!/usr/bin/env node
    import meow from 'meow';
    import foo from './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);

Interfaces

interface Flag

interface Flag<Type extends FlagType, Default, IsMultiple = false> {}

    property alias

    readonly alias?: string;

      property default

      readonly default?: Default;

        property isMultiple

        readonly isMultiple?: IsMultiple;

          property isRequired

          readonly isRequired?: boolean | IsRequiredPredicate;

            property type

            readonly type?: Type;

              interface Options

              interface Options<Flags extends AnyFlags> {}

                property allowUnknownFlags

                readonly allowUnknownFlags?: boolean;
                • Whether to allow unknown flags or not.

                  true

                property argv

                readonly argv?: readonly string[];
                • Custom arguments object.

                  process.argv.slice(2)

                property autoHelp

                readonly autoHelp?: boolean;
                • 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.

                property autoVersion

                readonly autoVersion?: boolean;
                • 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.

                property booleanDefault

                readonly booleanDefault?: boolean | null | undefined;
                • 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 1

                  ``` 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 // }, // โ€ฆ //} ```

                property description

                readonly description?: string | false;
                • Description to show above the help text. Default: The package.json "description" property.

                  Set it to false to disable it altogether.

                property flags

                readonly flags?: Flags;
                • 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. 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. - 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 *not* supported.

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

                  Example 1

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

                  return false; } } } ```

                property hardRejection

                readonly hardRejection?: boolean;
                • Whether to use [hard-rejection](https://github.com/sindresorhus/hard-rejection) or not. Disabling this can be useful if you need to handle process.on('unhandledRejection') yourself.

                  true

                property help

                readonly help?: 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](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/template_strings) 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.

                property importMeta

                readonly importMeta: ImportMeta;
                • Pass in [import.meta](https://nodejs.org/dist/latest/docs/api/esm.html#esm_import_meta). This is used to find the correct package.json file.

                property inferType

                readonly inferType?: boolean;
                • Infer the argument type.

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

                  false

                property pkg

                readonly pkg?: Record<string, unknown>;
                • package.json as an Object. Default: Closest package.json upwards.

                  _You most likely don't need this option._

                property version

                readonly version?: string | false;
                • Set a custom version output. Default: The package.json "version" property.

                  Set it to false to disable it altogether.

                interface Result

                interface Result<Flags extends AnyFlags> {}

                  property flags

                  flags: TypedFlags<Flags> & Record<string, unknown>;
                  • Flags converted to camelCase excluding aliases.

                  property help

                  help: string;
                  • The help text used with --help.

                  property input

                  input: string[];
                  • Non-flag arguments.

                  property pkg

                  pkg: PackageJson;
                  • The package.json object.

                  property showHelp

                  showHelp: (exitCode?: number) => void;
                  • Show the help text and exit with code.

                    Parameter exitCode

                    The exit code to use. Default: 2.

                  property showVersion

                  showVersion: () => void;
                  • Show the version text and exit.

                  property unnormalizedFlags

                  unnormalizedFlags: TypedFlags<Flags> & Record<string, unknown>;
                  • Flags converted camelCase including aliases.

                  Type Aliases

                  type AnyFlag

                  type AnyFlag = StringFlag | BooleanFlag | NumberFlag;

                    type AnyFlags

                    type AnyFlags = Record<string, AnyFlag>;

                      type BooleanFlag

                      type BooleanFlag = Flag<'boolean', boolean> | Flag<'boolean', boolean[], true>;

                        type FlagType

                        type FlagType = 'string' | 'boolean' | 'number';

                          type IsRequiredPredicate

                          type IsRequiredPredicate = (
                          flags: Readonly<AnyFlags>,
                          input: readonly string[]
                          ) => boolean;
                          • Callback function to determine if a flag is required during runtime.

                            Parameter flags

                            Contains the flags converted to camel-case excluding aliases.

                            Parameter input

                            Contains the non-flag arguments.

                            Returns

                            True if the flag is required, otherwise false.

                          type NumberFlag

                          type NumberFlag = Flag<'number', number> | Flag<'number', number[], true>;

                            type PossiblyOptionalFlag

                            type PossiblyOptionalFlag<Flag extends AnyFlag, FlagType> = Flag extends {
                            isRequired: true;
                            }
                            ? FlagType
                            : Flag extends { default: any }
                            ? FlagType
                            : FlagType | undefined;

                              type StringFlag

                              type StringFlag = Flag<'string', string> | Flag<'string', string[], true>;

                                type TypedFlag

                                type TypedFlag<Flag extends AnyFlag> = Flag extends { type: 'number' }
                                ? number
                                : Flag extends { type: 'string' }
                                ? string
                                : Flag extends { type: 'boolean' }
                                ? boolean
                                : unknown;

                                  type TypedFlags

                                  type TypedFlags<Flags extends AnyFlags> = {
                                  [F in keyof Flags]: Flags[F] extends { isMultiple: true }
                                  ? PossiblyOptionalFlag<Flags[F], Array<TypedFlag<Flags[F]>>>
                                  : PossiblyOptionalFlag<Flags[F], TypedFlag<Flags[F]>>;
                                  };

                                    Package Files (1)

                                    Dependencies (12)

                                    Dev Dependencies (6)

                                    Peer Dependencies (0)

                                    No peer dependencies.

                                    Badge

                                    To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                    You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/meow.

                                    • Markdown
                                      [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/meow)
                                    • HTML
                                      <a href="https://www.jsdocs.io/package/meow"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>