Command Syntax

Options and arguments

Command options and arguments can be defined using method parameters:

class Example2 {

	@Command(name = "hi", description = "Say hi to a given name", group = "greetings",
			help = "A command that greets the user with 'Hi ${name}!' with a configurable suffix. Example usage: hi -s=! John")
	public void sayHi(
			@Argument(index = 0, description = "the name of the person to greet",
					defaultValue = "world") String name,
			@Option(shortName = 's', longName = "suffix", description = "the suffix of the greeting message",
					defaultValue = "!") char suffix) {
		System.out.println("Hi " + name + suffix);
	}

}

Options are defined using @Option annotation, while arguments are defined using @Argument annotation. Options are named, while arguments are positional. Options can have short names (single character) and long names (multi-character).

Options can be validated using the Bean Validation API by adding validation annotations to the method parameters, see the Validating Command Options section for more details.

Parsing rules

Spring Shell follows the same parsing rules as Spring Boot, with enhanced capabilities following the POSIX style. Options can be specified in the long form of --key=value or --key value as well in the short form of -k=value or -k value. Options and arguments can be specified in any order. Arguments are 0-based indexed among other arguments:

CommandSyntax  ::= CommandName [SubCommandName]* [Option | Argument]*
CommandName    ::= String
SubCommandName ::= String
Option         ::= ShortOption | LongOption
ShortOption    ::= '-' Char ['='|' ']? String
LongOption     ::= '--' String ['='|' ']? String
Argument       ::= String

For example:

$>mycommand mysubcommand --optionA=value1 arg1 -b=value2 arg2 --optionC value3 -d value4

When an option is specified, it is always expected to have a value for that option, even if it is a boolean one. This is necessary to be able to distinguish option values from arguments. Moreover, short options cannot be grouped (e.g., -abc is not supported).

If your command does not have options, then arguments must be separated using "--" (POSIX style) to avoid ambiguity between arguments and subcommands:

$>mycommand -- arg1 arg2

Similarly, if your command defines subcommands that are used without options, then arguments must also be separated using "--" (POSIX style) to avoid ambiguity between arguments and subcommands:

$>mycommand mysubcommand -- arg1 arg2

To avoid ambiguity, named options should be preferred over positional arguments whenever possible, especially when subcommands are involved (see Command Line Interface Guidelines).

Customizing parsing rules

Spring Shell 4 provides a new API called CommandParser that allows you to customize the command parsing rules. If the default parsing rules do not fit your needs, you can implement your own parser by implementing the CommandParser interface. Once the custom parser is implemented, you can register it as a bean in the application context, and Spring Shell will use it for parsing commands.