Skip to main content
Module

x/cliffy/command/mod.ts>Command

Command line framework for deno 🦕 Including Commandline-Interfaces, Prompts, CLI-Table, Arguments Parser and more...
Extremely Popular
Go to Latest
class Command
Re-export
import { Command } from "https://deno.land/x/cliffy@v1.0.0-rc.3/command/mod.ts";

Chainable command factory class.

import { Command } from "./mod.ts";

export const cli = new Command()
  .name("todo")
  .description("Example command description")
  .globalOption("--verbose", "Enable verbose output.")
  .globalEnv("VERBOSE=<value>", "Enable verbose output.")
  .command("add <todo>", "Add todo.")
  .action(({ verbose }, todo: string) => {
    if (verbose) {
      console.log("Add todo '%s'.", todo);
    }
  })
  .command("delete <id>", "Delete todo.")
  .action(({ verbose }, id: string) => {
    if (verbose) {
      console.log("Delete todo with id '%s'.", id);
    }
  });

if (import.meta.main) {
  await cli.parse();
}

Type Parameters

optional
TParentCommandGlobals extends Record<string, unknown> | void = void
optional
TParentCommandTypes extends Record<string, unknown> | void = TParentCommandGlobals extends number ? any : void
optional
TCommandOptions extends Record<string, unknown> | void = TParentCommandGlobals extends number ? any : void
optional
TCommandArguments extends Array<unknown> = TParentCommandGlobals extends number ? any : []
optional
TCommandGlobals extends Record<string, unknown> | void = TParentCommandGlobals extends number ? any : void
optional
TCommandTypes extends Record<string, unknown> | void = TParentCommandGlobals extends number ? any : { number: number; integer: number; string: string; boolean: boolean; file: string; }
optional
TCommandGlobalTypes extends Record<string, unknown> | void = TParentCommandGlobals extends number ? any : void
optional
TParentCommand extends Command<any> | undefined = TParentCommandGlobals extends number ? any : undefined

Properties

private
_allowEmpty: boolean
private
optional
_globalParent: Command<any>
private
_groupName: string | null
private
optional
_help: HelpHandler
private
optional
_helpOption: Option
private
optional
_helpOptions: DefaultOption | false
private
_meta: Record<string, string>
private
_name: string
private
_noGlobals: boolean
private
optional
_parent: TParentCommand
private
optional
_shouldExit: boolean
private
_stopEarly: boolean
private
optional
_usage: string
private
_useRawArgs: boolean
private
optional
_versionOption: Option
private
optional
_versionOptions: DefaultOption | false
private
optional
actionHandler: ActionHandler
private
aliases: Array<string>
private
args: Array<Argument>
private
optional
argsDefinition: string
private
cmd: Command<any>
private
commands: Map<string, Command<any>>
private
completions: Map<string, Completion>
private
optional
defaultCommand: string
private
desc: Description
private
envVars: Array<EnvVar>
private
optional
errorHandler: ErrorHandler
private
examples: Array<Example>
private
optional
globalActionHandler: ActionHandler
private
hasDefaults: boolean
private
isExecutable: boolean
private
isGlobal: boolean
private
isHidden: boolean
private
literalArgs: Array<string>
private
options: Array<Option>
private
rawArgs: Array<string>
private
throwOnError: boolean
private
types: Map<string, TypeDef>
private
optional
ver: VersionHandler

Methods

private
execute(options: Record<string, unknown>, args: Array<unknown>): Promise<CommandResult>

Execute command.

private
executeGlobalAction(options: Record<string, unknown>, args: Array<unknown>)
private
exit(code?)
private
getErrorHandler(): ErrorHandler | undefined

Get error handler callback function.

Get help handler method.

private
getHelpOption(): Option | undefined
private
getSubCommand(ctx: ParseContext)
private
getVersionHandler(): VersionHandler | undefined

Get help handler method.

private
handleError(error: unknown): never
private
parseCommand(ctx: ParseContext): Promise<CommandResult>
private
parseGlobalOptionsAndEnvVars(ctx: ParseContext): Promise<void>
private
parseOptionsAndEnvVars(ctx: ParseContext, preParseGlobals: boolean): Promise<void>
private
registerDefaults(): this

Register default options like --version and --help.

protected
executeExecutable(args: string[])

Execute external sub-command.

protected
findEnvVar(names: readonly string[]): Promise<{ name: string; value: string; } | undefined>
protected
parseArguments(ctx: ParseContext, options: Record<string, unknown>): TCommandArguments

Parse command-line arguments.

protected
parseEnvVars(
ctx: ParseContext,
envVars: Array<EnvVar>,
validate?,
): Promise<void>

Read and validate environment variables.

protected
parseOptions(
ctx: ParseContext,
options: Option[],
unnamed 2?: ParseOptionsOptions,
): void

Parse raw command line arguments.

protected
parseType(type: ArgumentValue): unknown

Parse argument type.

protected
shouldExit(): boolean

Check whether the command should exit after printing help or version.

protected
shouldThrowErrors(): boolean

Check whether the command should throw errors or exit.

alias(alias: string): this

Add new command alias.

allowEmpty<TAllowEmpty extends boolean | undefined = undefined>(allowEmpty?: TAllowEmpty): false extends TAllowEmpty ? this : Command<Partial<TParentCommandGlobals>, TParentCommandTypes, Partial<TCommandOptions>, TCommandArguments, TCommandGlobals, TCommandTypes, TCommandGlobalTypes, TParentCommand>

Don't throw an error if the command was called without arguments.

arguments<TArguments extends TypedArguments<TArgs, Merge<TParentCommandTypes, Merge<TCommandGlobalTypes, TCommandTypes>>>, TArgs extends string = string>(args: TArgs): Command<TParentCommandGlobals, TParentCommandTypes, TCommandOptions, TArguments, TCommandGlobals, TCommandTypes, TCommandGlobalTypes, TParentCommand>

Set command arguments:

requiredArg:string [optionalArg: number] [...restArgs:string]

command<TCommand extends Command<(TGlobalOptions & Record<string, unknown>) | void | undefined, TGlobalTypes | void | undefined, Record<string, unknown> | void, Array<unknown>, Record<string, unknown> | void, Record<string, unknown> | void, Record<string, unknown> | void, Command<TGlobalOptions | void | undefined, TGlobalTypes | void | undefined, Record<string, unknown> | void, Array<unknown>, Record<string, unknown> | void, Record<string, unknown> | void, Record<string, unknown> | void, undefined>>, TGlobalOptions extends (TParentCommand extends Command<any> ? TParentCommandGlobals : Merge<TParentCommandGlobals, TCommandGlobals>), TGlobalTypes extends (TParentCommand extends Command<any> ? TParentCommandTypes : Merge<TParentCommandTypes, TCommandTypes>)>(
name: string,
cmd: TCommand,
override?: boolean,
): ReturnType<TCommand["reset"]> extends Command<Record<string, unknown> | void, Record<string, unknown> | void, infer Options, infer Arguments, infer GlobalOptions, infer Types, infer GlobalTypes, undefined> ? Command<TGlobalOptions, TGlobalTypes, Options, Arguments, GlobalOptions, Types, GlobalTypes, OneOf<TParentCommand, this>> : never

Add new sub-command.

command<TCommand extends Command<TGlobalOptions | void | undefined, TGlobalTypes | void | undefined, Record<string, unknown> | void, Array<unknown>, Record<string, unknown> | void, Record<string, unknown> | void, Record<string, unknown> | void, OneOf<TParentCommand, this> | undefined>, TGlobalOptions extends (TParentCommand extends Command<any> ? TParentCommandGlobals : Merge<TParentCommandGlobals, TCommandGlobals>), TGlobalTypes extends (TParentCommand extends Command<any> ? TParentCommandTypes : Merge<TParentCommandTypes, TCommandTypes>)>(
name: string,
cmd: TCommand,
override?: boolean,
): TCommand extends Command<Record<string, unknown> | void, Record<string, unknown> | void, infer Options, infer Arguments, infer GlobalOptions, infer Types, infer GlobalTypes, OneOf<TParentCommand, this> | undefined> ? Command<TGlobalOptions, TGlobalTypes, Options, Arguments, GlobalOptions, Types, GlobalTypes, OneOf<TParentCommand, this>> : never

Add new sub-command.

command<TNameAndArguments extends string, TArguments extends TypedCommandArguments<TNameAndArguments, TParentCommand extends Command<any> ? TParentCommandTypes : Merge<TParentCommandTypes, TCommandGlobalTypes>>>(
nameAndArguments: TNameAndArguments,
desc?: string,
override?: boolean,
): TParentCommandGlobals extends number ? Command<any> : Command<TParentCommand extends Command<any> ? TParentCommandGlobals : Merge<TParentCommandGlobals, TCommandGlobals>, TParentCommand extends Command<any> ? TParentCommandTypes : Merge<TParentCommandTypes, TCommandGlobalTypes>, void, TArguments, void, void, void, OneOf<TParentCommand, this>>

Add new sub-command.

Register global complete handler.

default(name: string): this

Set default command. The default command is executed when the program was called without any argument and if no action handler is registered.

env<N extends string, G extends TypedEnv<N, P, TCommandOptions, Merge<TParentCommandTypes, Merge<TCommandGlobalTypes, TCommandTypes>>, R>, MG extends MapValue<G, V>, R extends EnvVarOptions["required"] = undefined, P extends EnvVarOptions["prefix"] = undefined, V = undefined>(
name: N,
description: string,
options: Omit<EnvVarOptions, "value"> & { global: true; required?: R; prefix?: P; value?: EnvVarValueHandler<MapTypes<ValueOf<G>>, V>; },
): Command<TParentCommandGlobals, TParentCommandTypes, TCommandOptions, TCommandArguments, Merge<TCommandGlobals, MG>, TCommandTypes, TCommandGlobalTypes, TParentCommand>

Register a global environment variable.

env<TNameAndValue extends string, TEnvVar extends TypedEnv<TNameAndValue, TPrefix, TCommandOptions, Merge<TParentCommandTypes, Merge<TCommandGlobalTypes, TCommandTypes>>, TRequired>, TMappedEnvVar extends MapValue<TEnvVar, TMappedValue>, TRequired extends EnvVarOptions["required"] = undefined, TPrefix extends EnvVarOptions["prefix"] = undefined, TMappedValue = undefined>(
name: TNameAndValue,
description: string,
options?: Omit<EnvVarOptions, "value"> & { required?: TRequired; prefix?: TPrefix; value?: EnvVarValueHandler<MapTypes<ValueOf<TEnvVar>>, TMappedValue>; },
): Command<TParentCommandGlobals, TParentCommandTypes, Merge<TCommandOptions, TMappedEnvVar>, TCommandArguments, TCommandGlobals, TCommandTypes, TCommandGlobalTypes, TParentCommand>

Register an environment variable.

error(handler: ErrorHandler): this

Set custom error handler.

example(name: string, description: string): this

Register command example.

executable(): this

Make command executable.

getAliases(): string[]

Get command name aliases.

getArgsDefinition(): string | undefined

Get arguments definition. E.g: input-file:string output-file:string

getArgument(name: string): Argument | undefined

Get argument by name.

Get arguments.

getBaseCommand<TCommand extends Command<any>>(name: string, hidden?: boolean): TCommand | undefined

Get base command by name or alias.

getBaseCommands(hidden?: boolean): Array<Command<any>>

Get base commands.

getBaseCompletion(name: string): Completion | undefined

Get base completion by name.

Get base completions.

getBaseEnvVar(name: string, hidden?: boolean): EnvVar | undefined

Get base environment variable by name.

getBaseEnvVars(hidden?: boolean): EnvVar[]

Get base environment variables.

getBaseOption(name: string, hidden?: boolean): Option | undefined

Get base option by name.

getBaseOptions(hidden?: boolean): Option[]

Get base options.

getBaseType(name: string): TypeDef | undefined

Get base type by name.

Get base types.

getCommand<TCommand extends Command<any>>(name: string, hidden?: boolean): TCommand | undefined

Get command by name or alias.

getCommands(hidden?: boolean): Array<Command<any>>

Get commands.

getCompletion(name: string): Completion | undefined

Get completion by name.

Get completions.

getDescription(): string

Get command description.

getEnvVar(name: string, hidden?: boolean): EnvVar | undefined

Get environment variable by name.

getEnvVars(hidden?: boolean): EnvVar[]

Get environment variables.

getExample(name: string): Example | undefined

Get example with given name.

Get all examples.

getGlobalCommand<TCommand extends Command<any>>(name: string, hidden?: boolean): TCommand | undefined

Get global command by name or alias.

getGlobalCommands(hidden?: boolean): Array<Command<any>>

Get global commands.

getGlobalCompletion(name: string): Completion | undefined

Get global completions by name.

Get global completions.

getGlobalEnvVar(name: string, hidden?: boolean): EnvVar | undefined

Get global environment variable by name.

getGlobalEnvVars(hidden?: boolean): EnvVar[]

Get global environment variables.

getGlobalOption(name: string, hidden?: boolean): Option | undefined

Get global option from parent commands by name.

getGlobalOptions(hidden?: boolean): Option[]

Get global options.

getGlobalParent(): Command<any> | undefined

Get parent command from global executed command. Be sure, to call this method only inside an action handler. Unless this or any child command was executed, this method returns always undefined.

getGlobalType(name: string): TypeDef | undefined

Get global type by name.

Get global types.

getHelp(options?: HelpOptions): string

Get generated help.

getLiteralArgs(): string[]

Get all arguments defined after the double dash.

getLongVersion(): string

Returns command name, version and meta data.

Get main command.

getMeta(): Record<string, string>

Returns an object of metadata.

getMeta(name: string): string

Get metadata value by name.

getName(): string

Get command name.

getOption(name: string, hidden?: boolean): Option | undefined

Get option by name.

getOptions(hidden?: boolean): Option[]

Get options.

Get parent command.

getPath(name?: string): string

Get full command path.

getRawArgs(): string[]

Get original command-line arguments.

Get short command description. This is the first line of the description.

getType(name: string): TypeDef | undefined

Get type by name.

getTypes(): Array<TypeDef>

Get types.

Get auto generated command usage.

getVersion(): string | undefined

Get command version.

global(): this

Make command globally available.

globalComplete(
name: string,
complete: CompleteHandler,
options?: Omit<CompleteOptions, "global">,
): this

Register global complete handler.

globalEnv<TNameAndValue extends string, TGlobalEnvVars extends TypedEnv<TNameAndValue, TPrefix, TCommandOptions, Merge<TParentCommandTypes, Merge<TCommandGlobalTypes, TCommandTypes>>, TRequired>, TMappedGlobalEnvVars extends MapValue<TGlobalEnvVars, TMappedValue>, TRequired extends EnvVarOptions["required"] = undefined, TPrefix extends EnvVarOptions["prefix"] = undefined, TMappedValue = undefined>(
name: TNameAndValue,
description: string,
options?: Omit<GlobalEnvVarOptions, "value"> & { required?: TRequired; prefix?: TPrefix; value?: EnvVarValueHandler<MapTypes<ValueOf<TGlobalEnvVars>>, TMappedValue>; },
): Command<TParentCommandGlobals, TParentCommandTypes, TCommandOptions, TCommandArguments, Merge<TCommandGlobals, TMappedGlobalEnvVars>, TCommandTypes, TCommandGlobalTypes, TParentCommand>

Register a global environment variable.

globalOption<TFlags extends string, TGlobalOptions extends TypedOption<TFlags, TCommandOptions, Merge<TParentCommandTypes, Merge<TCommandGlobalTypes, TCommandTypes>>, undefined extends TConflicts ? TRequired : false, TDefaultValue>, TMappedGlobalOptions extends MapValue<TGlobalOptions, TMappedValue, TCollect>, TRequired extends OptionOptions["required"] = undefined, TCollect extends OptionOptions["collect"] = undefined, TConflicts extends OptionOptions["conflicts"] = undefined, TDefaultValue = undefined, TMappedValue = undefined>(
flags: TFlags,
desc: string,
opts?: Omit<GlobalOptionOptions<Partial<TCommandOptions>, TCommandArguments, MergeOptions<TFlags, TCommandGlobals, TGlobalOptions>, TParentCommandGlobals, TCommandTypes, TCommandGlobalTypes, TParentCommandTypes, TParentCommand>, "value"> & { default?: DefaultValue<TDefaultValue>; required?: TRequired; collect?: TCollect; value?: OptionValueHandler<MapTypes<ValueOf<TGlobalOptions>>, TMappedValue>; } | OptionValueHandler<MapTypes<ValueOf<TGlobalOptions>>, TMappedValue>,
): Command<TParentCommandGlobals, TParentCommandTypes, TCommandOptions, TCommandArguments, MergeOptions<TFlags, TCommandGlobals, TMappedGlobalOptions>, TCommandTypes, TCommandGlobalTypes, TParentCommand>

Register a global option.

globalType<THandler extends TypeOrTypeHandler<unknown>, TName extends string = string>(
name: TName,
handler: THandler,
options?: Omit<TypeOptions, "global">,
): Command<TParentCommandGlobals, TParentCommandTypes, TCommandOptions, TCommandArguments, TCommandGlobals, TCommandTypes, Merge<TCommandGlobalTypes, TypedType<TName, THandler>>, TParentCommand>
group(name: string | null): this

Enable grouping of options and set the name of the group. All option which are added after calling the .group() method will be grouped in the help output. If the .group() method can be use multiple times to create more groups.

Check if command has arguments.

hasCommand(name: string, hidden?: boolean): boolean

Checks whether a child command exists by given name or alias.

hasCommands(hidden?: boolean): boolean

Checks whether the command has sub-commands or not.

hasEnvVar(name: string, hidden?: boolean): boolean

Checks whether the command has an environment variable with given name or not.

hasEnvVars(hidden?: boolean): boolean

Checks whether the command has environment variables or not.

hasExample(name: string): boolean

Checks whether the command has an example with given name or not.

hasExamples(): boolean

Checks whether the command has examples or not.

hasOption(name: string, hidden?: boolean): boolean

Checks whether the command has an option with given name or not.

hasOptions(hidden?: boolean): boolean

Checks whether the command has options or not.

help(help: string | HelpHandler<Partial<TCommandOptions>, Partial<TCommandArguments>, TCommandGlobals, TParentCommandGlobals> | HelpOptions): this

Set command help.

helpOption(enable: false): this

Disable help option.

Set global help option.

hidden(): this

Hide command from help, completions, etc.

meta(name: string, value: string): this

Add meta data. Will be displayed in the auto generated help and in the output of the long version.

name(name: string): this

Set command name. Used in auto generated help and shell completions

noExit(): this

Same as .throwErrors() but also prevents calling Deno.exit after printing help or version with the --help and --version option.

noGlobals(): this

Disable inheriting global commands, options and environment variables from parent commands.

option<TFlags extends string, TGlobalOptions extends TypedOption<TFlags, TCommandOptions, Merge<TParentCommandTypes, Merge<TCommandGlobalTypes, TCommandTypes>>, undefined extends TConflicts ? TRequired : false, TDefault>, TMappedGlobalOptions extends MapValue<TGlobalOptions, TMappedValue, TCollect>, TRequired extends OptionOptions["required"] = undefined, TCollect extends OptionOptions["collect"] = undefined, TConflicts extends OptionOptions["conflicts"] = undefined, TDefault = undefined, TMappedValue = undefined>(
flags: TFlags,
desc: string,
opts: Omit<OptionOptions<Partial<TCommandOptions>, TCommandArguments, MergeOptions<TFlags, TCommandGlobals, TGlobalOptions>, TParentCommandGlobals, TCommandTypes, TCommandGlobalTypes, TParentCommandTypes, TParentCommand>, "value"> & { global: true; default?: DefaultValue<TDefault>; required?: TRequired; collect?: TCollect; value?: OptionValueHandler<MapTypes<ValueOf<TGlobalOptions>>, TMappedValue>; } | OptionValueHandler<MapTypes<ValueOf<TGlobalOptions>>, TMappedValue>,
): Command<TParentCommandGlobals, TParentCommandTypes, TCommandOptions, TCommandArguments, MergeOptions<TFlags, TCommandGlobals, TMappedGlobalOptions>, TCommandTypes, TCommandGlobalTypes, TParentCommand>

Add a global option.

option<TFlags extends string, TOptions extends TypedOption<TFlags, TCommandOptions, Merge<TParentCommandTypes, Merge<TCommandGlobalTypes, TCommandTypes>>, undefined extends TConflicts ? TRequired : false, TDefaultValue>, TMappedOptions extends MapValue<TOptions, TMappedValue, TCollect>, TRequired extends OptionOptions["required"] = undefined, TCollect extends OptionOptions["collect"] = undefined, TConflicts extends OptionOptions["conflicts"] = undefined, TDefaultValue = undefined, TMappedValue = undefined>(
flags: TFlags,
desc: string,
opts?: Omit<OptionOptions<MergeOptions<TFlags, TCommandOptions, TMappedOptions>, TCommandArguments, TCommandGlobals, TParentCommandGlobals, TCommandTypes, TCommandGlobalTypes, TParentCommandTypes, TParentCommand>, "value"> & { default?: DefaultValue<TDefaultValue>; required?: TRequired; collect?: TCollect; conflicts?: TConflicts; value?: OptionValueHandler<MapTypes<ValueOf<TOptions>>, TMappedValue>; } | OptionValueHandler<MapTypes<ValueOf<TOptions>>, TMappedValue>,
): Command<TParentCommandGlobals, TParentCommandTypes, MergeOptions<TFlags, TCommandOptions, TMappedOptions>, TCommandArguments, TCommandGlobals, TCommandTypes, TCommandGlobalTypes, TParentCommand>

Register an option.

parse(args?: string[]): Promise<TParentCommand extends Command<any> ? CommandResult<Record<string, unknown>, Array<unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, undefined> : CommandResult<MapTypes<TCommandOptions>, MapTypes<TCommandArguments>, MapTypes<TCommandGlobals>, MapTypes<TParentCommandGlobals>, TCommandTypes, TCommandGlobalTypes, TParentCommandTypes, TParentCommand>>

Parse command line arguments and execute matched command.

removeCommand(name: string): Command<any> | undefined

Remove sub-command by name or alias.

removeOption(name: string): Option | undefined

Remove option by name.

reset(): OneOf<TParentCommand, this>

Reset internal command reference to main command.

select<TOptions extends Record<string, unknown> | void = any, TArguments extends Array<unknown> = any, TGlobalOptions extends Record<string, unknown> | void = any>(name: string): Command<TParentCommandGlobals, TParentCommandTypes, TOptions, TArguments, TGlobalOptions, TCommandTypes, TCommandGlobalTypes, TParentCommand>

Set internal command pointer to child command with given name.

showHelp(options?: HelpOptions): void

Output generated help without exiting.

Outputs command name, version and meta data.

showVersion(): void

Output generated help without exiting.

stopEarly(stopEarly?): this

Enable stop early. If enabled, all arguments starting from the first non option argument will be passed as arguments with type string to the command action handler.

For example: command --debug-level warning server --port 80

Will result in: - options: { debugLevel: 'warning' } - args: ['server', '--port', '80']

throw(error: Error): never

Handle error. If throwErrors is enabled the error will be thrown, otherwise a formatted error message will be printed and Deno.exit(1) will be called. This will also trigger registered error handlers.

throwErrors(): this

Throw validation errors instead of calling Deno.exit() to handle validation errors manually.

A validation error is thrown when the command is wrongly used by the user. For example: If the user passes some invalid options or arguments to the command.

This has no effect for parent commands. Only for the command on which this method was called and all child commands.

Example:

import { Command, ValidationError } from "./mod.ts";

const cmd = new Command();
// ...

try {
  cmd.parse();
} catch(error) {
  if (error instanceof ValidationError) {
    cmd.showHelp();
    Deno.exit(1);
  }
  throw error;
}
type<THandler extends TypeOrTypeHandler<unknown>, TName extends string = string>(
name: TName,
handler: THandler,
options?: TypeOptions,
): Command<TParentCommandGlobals, TParentCommandTypes, TCommandOptions, TCommandArguments, TCommandGlobals, Merge<TCommandTypes, TypedType<TName, THandler>>, TCommandGlobalTypes, TParentCommand>

Register custom type.

usage(usage: string): this

Set the command usage. Defaults to arguments.

useRawArgs(useRawArgs?): Command<void, void, void, Array<string>, void, void, void, TParentCommand>

Disable parsing arguments. If enabled the raw arguments will be passed to the action handler. This has no effect for parent or child commands. Only for the command on which this method was called.

versionOption(enable: false): this

Disable version option.

Set global version option.