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 process 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.
`resolveSubContext`	`Function` Defines a resolver function for the command. The resolveSubContext is used to resolve context before the handler is executed.
`process`	`Function` Defines a process function for the command. The process 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.
`process`	`CommandProcessFunction<ProcessContext<Name, Context, CommandFlags>>` Returns the process function for this command.
`resolveSubContext`	`CommandResolveSubContextFunction<ResolveSubContextCtx<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.
`setResolveSubContext`	`(fn: CommandResolveSubContextFunction<ResolveSubContextCtx<Name, Context>, SubCommandContext>) => void` Sets the resolveSubContext function for this command, which can provide context for sub-commands.
`setProcess`	`(fn: CommandProcessFunction<ProcessContext<Name, Context, CommandFlags>>) => void` Sets the process 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:


// @filename: @hyperse/wizard/dist/index.d.ts
import {  } from '@hyperse/wizard';
 
const  = <
  'deploy',
  { : { : string; : string } }
>('deploy', {
  //locale message key
  : 'plugins.deploy.description',
})
  .({
    : {
      : ,
      : 'f',
      //locale message key
      : 'plugins.deploy.flags.fileType',
      : 'js',
    },
    : {
      : ,
      : 'o',
      //locale message key
      : 'plugins.deploy.flags.ossType',
      : 'aliyun',
    },
    : {
      : 'i',
      : 'plugins.deploy.flags.ignore',
      // Array type
      // To accept multiple values of a flag, wrap the type with an array:
      : [],
      : [],
    },
    : {
      : [],
      // Use a function to return an object or array
      : () => [1, 2],
    },
  })
  .(() => {
    //do something
  });
 
// execute command
// node ./dist/cli.js deploy --fileType=ts --ossType=tencent --ignore=a --ignore=b --manyNumbers=1 --manyNumbers=2 --manyNumbers=3

Advanced Usage

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

Parameters:

Name	Type	Default
`name`	`Name` The name of the command, used as the identifier in the CLI.
`options`	`CommandOptions` The detailed configuration for the command, including description, arguments, flags, process, etc.

Returns:

CommandBuilder<Name, Ctx, object, Flags, { [K in Name]: Ctx & { flags: { [x: string]: never; noColor: boolean; logLevel: "Error" | "Warn" | "Info" | "Debug" | "Verbose" | undefined; hpsAppEnv: string; hpsEnvPath: string | undefined; projectCwd: string; }; }; }>

Returns a command builder object for further configuration and subcommand registration.

Example:


// @filename: @hyperse/wizard/dist/index.d.ts
import {  } from '@hyperse/wizard';
 
const  = <
  'deploy',
  { : { : string; : string } }
>('deploy', {
  //locale message key
  : 'plugins.deploy.description',
});