meowtastic

A helper library for meow. Automatically create stylized help text and more.

Features

• Automatically styles Markdown code spans.
• Displays a usage example which can be customized.
• Lists all available flags in alphabetical order. Displays descriptions as well if specified.
• Is easily themeable.
• Provides optional descriptions and short flags for the help and version flags.
• Supports the NO_COLOR environment variable standard.
• Wraps help text at 80 columns by default, although this can be disabled.
• Provides variables which expand into the choices or default values of flags.

Install

npm install meowtastic

Usage

import meow from 'meow';
import { type Config, getHelpTextAndOptions } from 'meowtastic';

// Includes all the options that `meow` accepts.
// See https://github.com/sindresorhus/meow#api for reference.
const config: Config = {
  arguments: [
    { name: 'file', isRequired: true },
    { name: 'additional files...' }
  ],
  flags: {
    example: {
      default: 'this',
      description: 'An example... yeah! Defaults to %DEFAULT%.',
      shortFlag: 'e',
      type: 'string'
    },
    codeSpans: {
      description: 'Use `backticks` to format text.',
      shortFlag: 'c',
      type: 'boolean'
    },
    choices: {
      description: 'A list of choices. Options are %CHOICES_AND%.',
      shortFlag: 'C',
      type: 'string',
      choices: ['one', 'two', 'three']
    }
  },
  importMeta: import.meta,
  packageOverrides: {
    bin: { meowtastic: 'path/to/bin' }
  }
};

meow(...getHelpTextAndOptions(config));

Or if desired, a more granular approach:

import meow from 'meow';
import {
  type Config,
  type Flags,
  getHelpAndVersionFlags,
  getHelpText
} from 'meowtastic';

const flags: Flags = {
  ...getHelpAndVersionFlags(), // <- Add a description and short flag to `help` and `version`.
  example: {
    default: 'this',
    description: 'An example... yeah! Defaults to %DEFAULT%.',
    shortFlag: 'e',
    type: 'string'
  },
  codeSpans: {
    description: 'Use `backticks` to format text.',
    shortFlag: 'c',
    type: 'boolean'
  },
  choices: {
    description: 'A list of choices. Options are %CHOICES_AND%.',
    shortFlag: 'C',
    type: 'string',
    choices: ['one', 'two', 'three']
  }
};

const config: Config = {
  arguments: [
    { name: 'file', isRequired: true },
    { name: 'additional files...' }
  ],
  flags,
  importMeta: import.meta,
  packageOverrides: {
    bin: { meowtastic: 'path/to/bin' }
  }
};

meow(
  getHelpText(config),
  {
    description: false,
    flags,
    importMeta: import.meta
  }
);

Also, commands are supported:

import meow from 'meow';
import { type Config, getHelpTextAndOptions } from 'meowtastic';

// Includes all the options that `meow` accepts.
// See https://github.com/sindresorhus/meow#api for reference.
const config: Config = {
  commands: {
    initialize: {
      arguments: [{ name: 'file', isRequired: false }],
      description: 'Initialize a new project.'
    }
  },
  flags: {
    example: {
      default: 'this',
      description: 'An example... yeah! Defaults to %DEFAULT%.',
      shortFlag: 'e',
      type: 'string'
    },
    codeSpans: {
      description: 'Use `backticks` to format text.',
      shortFlag: 'c',
      type: 'boolean'
    },
    choices: {
      description: 'A list of choices. Options are %CHOICES_AND%.',
      shortFlag: 'C',
      type: 'string',
      choices: ['one', 'two', 'three']
    }
  },
  importMeta: import.meta,
  packageOverrides: {
    bin: { meowtastic: 'path/to/bin' }
  }
};

meow(...getHelpTextAndOptions(config));

See the "types" file (src/types.ts in the source distribution and dist/types/types.d.ts in the package distribution) for more information.

Theming

A theme has the following type signature:

// All these cases are exactly like they sound, except for "title". It's a faux titlecase format
// in which the first letter of each word is capitalized.
export type TextCase = 'lower' | 'title' | 'upper';

// All the `string` types below can accept a string in the form of anything accepted by
// [chalk-pipe](https://www.npmjs.com/package/chalk-pipe) for formatting. Of note, if you do
// not want to use any styling, you can pass an empty string.
export type Theme = {
  // Required arguments displayed in the usage section.
  argument?: string | [string, TextCase];

  // The application binary's name.
  bin?: string;

  // Markdown code spans in the app description or flag descriptions.
  code?: string;

  // Commands displayed in the commands section.
  command?: string | [string, TextCase];

  // Flags displayed in the options section.
  flag?: string;

  // Section headers such as "Usage" and "Options".
  header?: string | [string, TextCase];

  // Optional arguments displayed in the usage section.
  option?: string | [string, TextCase];

  // The shell prompt symbol ("$") used in the usage section.
  promptSymbol?: string;
};

You can modify the default theme:

import meow from 'meow';
import { getDefaultHelpTextTheme, getHelpTextAndOptions } from 'meowtastic';

const theme = getDefaultHelpTextTheme();

theme.header = ['blue.underline', 'upper'];

meow(...getHelpTextAndOptions({ importMeta: import.meta, theme }));

Or create a new theme from scratch:

import meow from 'meow';
import { type Theme, getHelpTextAndOptions } from 'meowtastic';

const theme: Theme = {
  bin: 'bold.green',
  code: 'bold.yellow',
  command: 'bold',
  flag: 'bold.blue',
  header: ['bold.underline.blue', 'upper'],
  option: 'bold.yellow',
  promptSymbol: 'bold.green'
};

meow(...getHelpTextAndOptions({ importMeta: import.meta, theme }));

Prior Art

• cli-meow-help
• meow-helper

License

The BSD 3-Clause License. See the license file for details.