Command

The Command is the core mechanism within the @hyperse/wizard framework that enables definition, parsing, and execution of CLI commands. This system provides type-safe command creation, argument parsing, and handler execution while integrating with the broader event-driven architecture.

CommandBuilder

Name

Name	Type	Default
`Name`	`string \| typeof Root`

Options

Name	Type	Default
`description`	`LocaleMessageResolver` The description of the command, supports i18n.
`example`	`LocaleMessageResolver` The example of the command, supports i18n.
`help`	`LocaleMessageResolver` The help message for the command, supports i18n.

Properties

Name	Type	Default
`use`	`Function` Registers sub-commands for the current command. Returns a new CommandBuilder with merged sub-command contexts and command maps.
`flags`	`Function` Defines the flags for the command. Returns a new CommandBuilder with the updated flags type.
`resolver`	`Function` Defines a resolver function for the command. The resolver is used to resolve context before the handler is executed.
`handler`	`Function` Defines a handler function for the command. The handler is executed when the command is invoked.
`getCommand`	`Function` Extracts the final Command object from the builder, which can be registered or executed.

Command Properties

Name	Type	Default
`name`	`Name` Returns the name of the command.
`description`	`LocaleMessageResolver` Returns the description of the command.
`example`	`LocaleMessageResolver \| undefined` Returns the example of the command.
`help`	`LocaleMessageResolver \| undefined` Returns the help message of the command.
`flags`	`CommandFlags` Returns the parsed flags for the command.
`parentCommand`	`Command<Name, any, any, any>` Returns the parent command, if any.
`subCommands`	`Command<Name, any, any, any>[]` Returns the list of sub-commands for this command.
`handler`	`CommandHandlerFunction<HandlerContext<Name, Context, CommandFlags>>` Returns the handler function for this command.
`resolver`	`CommandResolverFunction<ResolverContext<Name, Context>, SubCommandContext>` Returns the resolver function for this command.
`setFlags`	`(flags: CommandFlags) => void` Sets the parsed flags for the command.
`setParentCommand`	`<ParentCommandType extends Command<any, any, any, any>>(parentCommand: ParentCommandType) => void` Sets the parent command for this command.
`setSubCommands`	`<SubCommandType extends Command<any, any, any, any>>(subCommands: SubCommandType[]) => void` Sets the list of sub-commands for this command.
`setResolver`	`(fn: CommandResolverFunction<ResolverContext<Name, Context>, SubCommandContext>) => void` Sets the resolver function for this command, which can provide context for sub-commands.
`setHandler`	`(fn: CommandHandlerFunction<HandlerContext<Name, Context, CommandFlags>>) => void` Sets the handler function for this command, which is executed when the command is invoked.

Flags Configuration

Wizard’s flag parsing is powered by type-flag and comes with many features:

Array & Custom types
Flag delimiters: —flag value, —flag=value, —flag:value, and —flag.value
Combined aliases: -abcd 2 → -a -b -c -d 2
End of flags : Pass in — to end flag parsing
Unknown flags: Unexpected flags stored in unknownFlags

Read the type-flag docs to learn more.

Flags can be specified in the flags object-property, where the key is the flag name, and the value is a flag type function or an object that describes the flag.

The flag name is recommended to be in camelCase as it will be interpreted to parse kebab-case equivalents.

The flag type function can be any function that accepts a string and returns the parsed value. Default JavaScript constructors should cover most use-cases: String, Number, Boolean, etc.

The flag description object can be used to store additional information about the flag, such as alias, default, and description. To accept multiple values for a flag, wrap the type function in an array.

All of the provided information will be used to generate better help documentation.

Example:

cli.ts


import { defineCommand } from '@hyperse/wizard';
 
const deployCmd = defineCommand<
  'deploy',
  { ctx: { fileType: string; ossType: string } }
>('deploy', {
  //locale message key
  description: 'plugins.deploy.description',
})
  .flags({
    fileType: {
      type: String,
      alias: 'f',
      //locale message key
      description: 'plugins.deploy.flags.fileType',
      default: 'js',
    },
    ossType: {
      type: String,
      alias: 'o',
      //locale message key
      description: 'plugins.deploy.flags.ossType',
      default: 'aliyun',
    },
  })
  .handler((ctx) => {
    //do something
  });
 
// execute command
// node ./dist/cli.js deploy --fileType=ts --ossType=tencent

Advanced Usage

To seperate handlers from the cli definition, you can use the defineCommand utility function:

Parameters:

Name	Type	Default
`name`	`Name`
`options`	`CommandOptions`

Returns:

CommandBuilder<Name, Ctx, object, { [K in Name]: Ctx; }, Flags>

Example:

defineCommand.ts


import { defineCommand } from '@hyperse/wizard';
 
const deployCmd = defineCommand<
  'deploy',
  { ctx: { fileType: string; ossType: string } }
>('deploy', {
  //locale message key
  description: 'plugins.deploy.description',
});