Skip to content

Command handler signature

Rmannn edited this page May 21, 2021 · 6 revisions

Signature

(...commandArguments: any[]; options: object, commandInstance: commander.Command) => Promise<any> | any

Your handler will receive all command arguments, the options of the current command.
The last argument is the command instance from commander.

Command Options

By default the presence of an option is not required.

  • If you need to force the presence of an option, set the required options to true.
  • If you need to force the presence of the argument of an option, you have to use <options> instead of [options]

With option.required = false
-o, --option => option is optional and will be true if specified
-o, --option <oValue> option is optional and oValue argument is required
-o, --option [oValue] option is optional and oValue argument is also optional

With option.required = true
-o, --option option is required and will be true
-o, --option <oValue> option is required and oValue argument is required
-o, --option [oValue] option is required but oValue argument is optional

You can use variadic option argument using [oValue...] and <oValue...>, in this case oValue will be an array. Details from commander

How to define options and global options

Global options (or parent command options) are declared on one of the parent command.

To delcare root options (for the whole cli program) you have to defined them on the root command. You can get the root command using the method getRootCli of the ConsoleService

const root = this.consoleService.getRootCli();
root.options({...}) or root.requiredOption({...}) // see npm commander packages for more details

Examples

Interface GlobalOptions {
    globalOption?: any
}

Interface Options {
    option1?: any
    option2: any
}

Using ConsoleService

@Injectable()
class MyService {
    constructor(private readonly consoleService: ConsoleService){
        const cli = this.consoleService.createGroupCommand({
            description: 'A complete command handler',
            command: 'myCommandWithArgumentsAndOptions <arg1> <arg2>',
            options: [
                {
                    flags: '-g, --globalOption <value>',
                    required: false
                }
            ]
        });
        this.consoleService.createCommand({
                command: 'myCommandWithArgumentsAndOptions <arg1> <arg2>',
                options: [
                    {
                        flags: '-o1, --option1 <o1Value>',
                        required: false
                    },
                    {
                        flags: '-o2, --option2 <o1Value>',
                        required: true
                    }
                ]
            }, 
            this.commandHandler, // you can also pass an object {instance: this, methodName: 'commandHandler'}
            cli
        );
    }

    commandHandler(arg1: string, arg2: string, options: Options, command: commander.Command): void {
        // read command arguments
        console.log(arg1, arg2);
        
        // read the command options
        console.log(options); // or using the command instance command.opts()

        // read the global options from the parent (group command options)
        const parentOptions = command.parent?.opts();

        // you can retrieve parent options of any parent in the stack
        const parentOptions = command.parent?.parent?.parent?.opts();

    }
}

Using @decorators

@Console({
    command: "cli",
    options: [
        {
            flags: '-g, --globalOption <value>',
            required: false
        }
    ]
})
class MyService {
    @Command({
        command: 'myCommandWithArgumentsAndOptions <arg1> <arg2>',
        options: [
            {
                flags: '-o1, --option1 <o1Value>',
                required: false
            },
            {
                flags: '-o2, --option2 <o1Value>',
                required: true
            }
        ]
    })
    commandHandler(arg1: string, arg2: string, options: Options, command: commander.Command): void {
        // read command arguments
        console.log(arg1, arg2);
        
        // read the command options
        console.log(options); // or using the command instance command.opts()

        // read the global options from the parent (group command options)
        const parentOptions = command.parent?.opts();

        // you can retrieve parent options of any parent in the stack
        const parentOptions = command.parent?.parent?.parent?.opts();

    }
}