Skip to content

Function: cli() ​

Run the command.

Call Signature ​

ts
export async function cli<
  A extends Args = Args,
  G extends GunshiParams = { args: A; extensions: {} }
>(args: string[], entry:
    | (Command<NoInferParams<G>> & { args?: A & UnknownArgKeys<A> })
    | CommandRunner<NoInferParams<G>>
    | LazyCommand<NoInferParams<G>>, options?: CliOptions<NoInferParams<G>>): Promise<string | undefined>

Run the command.

An object written as the entry command is typed by its args, as with define: ctx.values of its run are inferred from them, and a key that an argument does not have is an error.

Type Parameters ​

NameDescription
A extends Args = ArgsThe type of arguments of the entry command, inferred from its args.
G extends GunshiParams = { args: A; extensions: {} }A type extending GunshiParams, which is not inferred: { args: A; extensions: {} }.

Parameters ​

NameTypeDescription
argsstring[]Command line arguments
entry(Command<NoInferParams<G>> & { args?: A & UnknownArgKeys<A> }) | CommandRunner<NoInferParams<G>> | LazyCommand<NoInferParams<G>>A entry command, an inline command runner, or a lazily-loaded command
optionsCliOptions<NoInferParams<G>>A CLI options (optional)

Returns ​

Promise<string | undefined> — A rendered usage or undefined. if you will use CliOptions.usageSilent option, it will return rendered usage string. It is also undefined when the arguments fail validation and the errors are reported to stderr (see CliOptions.renderValidationErrors).

Call Signature ​

ts
export async function cli<G extends GunshiParamsConstraint>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>

Run the command.

Type Parameters ​

NameDescription
G extends GunshiParamsConstraintA type extending GunshiParams to specify the shape of command and cli options.

Parameters ​

NameTypeDescription
argsstring[]Command line arguments
entryCommand<G> | CommandRunner<G> | LazyCommand<G>A entry command, an inline command runner, or a lazily-loaded command
optionsCliOptions<G>A CLI options (optional)

Returns ​

Promise<string | undefined> — A rendered usage or undefined. if you will use CliOptions.usageSilent option, it will return rendered usage string. It is also undefined when the arguments fail validation and the errors are reported to stderr (see CliOptions.renderValidationErrors).

Call Signature ​

ts
export async function cli<
  E extends ExtendContext = ExtendContext,
  G extends GunshiParams = { args: Args; extensions: E }
>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>

Run the command.

Type Parameters ​

NameDescription
E extends ExtendContext = ExtendContextAn ExtendContext type to specify the shape of command and cli options.
G extends GunshiParams = { args: Args; extensions: E }-

Parameters ​

NameTypeDescription
argsstring[]Command line arguments
entryCommand<G> | CommandRunner<G> | LazyCommand<G>A entry command, an inline command runner, or a lazily-loaded command
optionsCliOptions<G>A CLI options (optional)

Returns ​

Promise<string | undefined> — A rendered usage or undefined. if you will use CliOptions.usageSilent option, it will return rendered usage string. It is also undefined when the arguments fail validation and the errors are reported to stderr (see CliOptions.renderValidationErrors).

Call Signature ​

ts
export async function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>

Run the command.

Type Parameters ​

NameDescription
G extends GunshiParams = DefaultGunshiParamsA type extending GunshiParams to specify the shape of command and cli options.

Parameters ​

NameTypeDescription
argsstring[]Command line arguments
entryCommand<G> | CommandRunner<G> | LazyCommand<G>A entry command, an inline command runner, or a lazily-loaded command
optionsCliOptions<G>A CLI options (optional)

Returns ​

Promise<string | undefined> — A rendered usage or undefined. if you will use CliOptions.usageSilent option, it will return rendered usage string. It is also undefined when the arguments fail validation and the errors are reported to stderr (see CliOptions.renderValidationErrors).

Call Signature ​

ts
export async function cli(args: string[], entry: EntryCommandable, options?: CliOptions): Promise<string | undefined>

Run the command.

This overload takes a command of another copy of the types of gunshi, such as a command of @gunshi/definition, whose types the overloads above cannot compare. Its arguments are checked as Args, and its runner returns what a runner returns.

Note: This overload MUST be last in the overload list. TypeScript checks overloads in declaration order and selects the first matching one.

Parameters ​

NameTypeDescription
argsstring[]Command line arguments
entryEntryCommandableA command-like object (command, command runner, or lazy command)
optionsCliOptionsA CLI options (optional)

Returns ​

Promise<string | undefined> — A rendered usage or undefined. if you will use CliOptions.usageSilent option, it will return rendered usage string. It is also undefined when the arguments fail validation and the errors are reported to stderr (see CliOptions.renderValidationErrors).

Released under the MIT License.