Spring Shell Reference Documentation

For the purpose of this tutorial, we create a simple Spring Boot application by using start.spring.io where you can choose Spring Shell dependency. This minimal application depends only on spring-boot-starter and spring-shell-starter.

With maven you’re expected to have something like:

With gradle you’re expected to have something like:

Once compiled it can be run either in interactive mode:

Or in non-interactive mode:

Now we can add our first command. To do so, create a new class (named whatever you want) and annotate it with @ShellComponent which is a variation of @Component that is used to restrict the set of classes that are scanned for candidate commands.

Then we can create a helloWorld method that takes String as an argument and returns it with "Hello world". Add @ShellMethod and optionally change command name using key parameter. You can use @ShellOption to define argument default value if it’s not given when running a command.

New hello-world command becomes visible to help:

And you can run it:

The rest of this document delves deeper into the whole Spring Shell programming model.

There are two different ways to define a command: through an annotation model and through a programmatic model. In the annotation model, you define your methods in a class and annotate the class and the methods with specific annotations. In the programmatic model, you use a more low level approach, defining command registrations (either as beans or by dynamically registering with a command catalog).

When your shell starts to provide a lot of functionality, you may end up with a lot of commands, which could be confusing for your users. By typing help, they would see a daunting list of commands, organized in alphabetical order, which may not always be the best way to show the available commands.

To alleviate this possible confusion, Spring Shell provides the ability to group commands together, with reasonable defaults. Related commands would then end up in the same group (for example, User Management Commands) and be displayed together in the help screen and other places.

By default, commands are grouped according to the class they are implemented in, turning the camelCase class name into separate words (so URLRelatedCommands becomes URL Related Commands). This is a sensible default, as related commands are often already in the class anyway, because they need to use the same collaborating objects.

If, however, this behavior does not suit you, you can override the group for a command in the following ways, in order of priority:

The following listing shows an example:

Registered commands do not always make sense, due to the internal state of the application. For example, there may be a download command, but it only works once the user has used connect on a remote server. Now, if the user tries to use the download command, the shell should explain that the command exists but that it is not available at the time. Spring Shell lets you do that, even letting you provide a short explanation of the reason for the command not being available.

There are three possible ways for a command to indicate availability. They all use a no-arg method that returns an instance of Availability. Consider the following example:

The connect method is used to connect to the server (details omitted), altering the state of the command through the connected boolean when done. The download command as marked as unavailable until the user has connected, thanks to the presence of a method named exactly as the download command method with the Availability suffix in its name. The method returns an instance of Availability, constructed with one of the two factory methods. If the command is not available, an explanation has to be provided. Now, if the user tries to invoke the command while not being connected, here is what happens:

Information about currently unavailable commands is also used in the integrated help. See Help.

If naming the availability method after the name of the command method does not suit you, you can provide an explicit name by using the @ShellMethodAvailability annotation:

Finally, it is often the case that several commands in the same class share the same internal state and, thus, should all be available or unavailable as a group. Instead of having to stick the @ShellMethodAvailability on all command methods, Spring Shell lets you flip things around and put the @ShellMethodAvailabilty annotation on the availability method, specifying the names of the commands that it controls:

Exceptions happen from a user code wether it is intentional or not. This section describes how spring-shell handles exceptions and gives instructions and best practices how to work with it.

Many command line applications when applicable return an exit code which running environment can use to differentiate if command has been executed successfully or not. In a spring-shell this mostly relates when a command is run on a non-interactive mode meaning one command is always executed once with an instance of a spring-shell. Take a note that exit code always relates to non-interactive shell.

It is possible to hide a command which is convenient in cases where it is not yet ready for prime time, is meant for debugging purposes or you have any other reason you dont want to advertise its presense.

Hidden command can be executed if you know it and its options. It is effectively removed from:

Below is an example how to define command as hidden. It shows available builder methods to define hidden state.

Spring Shell has a build-in help command but not all favour getting command help from it as you always need to call it with arguments for target command. It’s common in many cli frameworks for every command having options --help and -h to print out command help.

Default functionality is that every command will get modified to have options --help and -h, which if present in a given command will automatically short circuit command execution into a existing help command regardless what other command-line options is typed.

Below example shows its default settings.

It is possible to change default behaviour via configuration options.

Command registration can define InteractionMode which is used to hide commands depending which mode shell is executing. More about that in Interaction Mode.

You can define it with CommandRegisration.

Or with @ShellMethod.

When something needs to get written into your console you can always use JDK’s System.out which then goes directly into JDK’s own streams. Other recommended way is to use JLine’s Terminal and get writer instance from there.

If using target endpoints, i.e. consumer which is not expected to return anything given CommandContext contains reference to Terminal and writer can be accessed from there.

It’s possible to autowire Terminal to get access to its writer.

Options can be defined within a target method as annotations in a method arguments or with programmatically with CommandRegistration.

Having a target method with argument is automatically registered with a matching argument name.

@ShellOption annotation can be used to define an option name if you don’t want it to be same as argument name.

If option name is defined without prefix, either - or --, it is discovered from ShellMethod#prefix.

Programmatic way with CommandRegistration is to use method adding a long name.

Short style POSIX option in most is just a synonym to long format but adds additional feature to combine those options together. Having short options a, b, c can be used as -abc.

Programmatically short option is defined by using short name function.

Short option with combined format is powerful if type is defined as a flag which means type is a boolean. That way you can define a presense of a flags as -abc, -abc true or -abc false.

With annotation model you can define short argument directly.

Sometimes, you want to have more fine control of how many parameters with an option are processed when parsing operations happen. Arity is defined as min and max values, where min must be zero or a positive integer and max has to be more or equal to min.

Arity can also be defined as an OptionArity enum, which are shortcuts shown in below table OptionArity.

The annotation model supports defining only the max value of an arity.

One of a use cases to manually define arity is to impose restrictions how many parameters option accepts.

In above example we have option arg1 and it’s defined as type String[]. Arity defines that it needs at least 1 parameter and not more that 2. As seen in below spesific exceptions TooManyArgumentsOptionException and NotEnoughArgumentsOptionException are thrown to indicate arity mismatch.

Positional information is mostly related to a command target method:

Usually arguments are mapped to an option when those are defined in a command line whether it’s a long or short option. Generally speaking there are options, option arguments and arguments where latter are the ones which are not mapped to any spesific option.

Unrecognised arguments can then have a secondary mapping logic where positional information is important. With option position you’re essentially telling command parsing how to interpret plain raw ambiguous arguments.

Let’s look what happens when we don’t define a position.

Option arg1 is required and there is no info what to do with argument one resulting error for missing option.

Now let’s define a position 0.

Arguments are processed until we get up to 2 arguments.

An option is either required or not and, generally speaking, how it behaves depends on a command target:

In the annotation model, there is no direct way to define if argument is optional. Instead, it is instructed to be NULL:

Having a default value for an option is somewhat related to Optional Value, as there are cases where you may want to know if the user defined an option and change behavior based on a default value:

The annotation model also supports defining default values:

Spring Shell integrates with the Bean Validation API to support automatic and self-documenting constraints on command parameters.

Annotations found on command parameters and annotations at the method level are honored and trigger validation prior to the command executing. Consider the following command:

From the preceding example, you get the following behavior for free:

Option Label has no functional behaviour within a shell itself other than what a default help command outputs. Within a command documentation a type of an option is documented but this is not always super useful. Thus you may want to give better descriptive word for an option.

Defining label is then shown in help.

This section talks about how particular data type is used as an option value.

If there is a need to modify option long names that can be done using OptionNameModifier interface which is a simple Function<String, String>. In this interface original option name goes in and modified name comes out.

Modifier can be defined per OptionSpec in CommandRegistration, defaulting globally as bean or via configuration properties. Modifier defined manually in OptionSpec takes takes precedence over one defined globally. There is no global modifier defined on default.

You can define one with an option in CommandRegistration.

Add one singleton bean as type OptionNameModifier and that becomes a global default.

It’s also possible to just add configuration property with spring.shell.option.naming.case-type which auto-configures one based on a type defined.

noop is to do nothing, camel, snake, kebab, pascal activates build-in modifiers for camelCase, snake_case, kebab-case or PascalCase respectively.

For example options defined in an annotated method like this.

On default help for that command shows names coming directly from @ShellOption.

Define spring.shell.option.naming.case-type=kebab and default modifier is added and option names then look like.

Hints for completions are calculated with function or interface style methods which takes CompletionContext and returns a list of CompletionProposal instances. CompletionContext gives you various information about a current context like command registration and option.

Option values with builder based command registration can be defined per option.

Option values with annotation based command registration are handled via ValueProvider interface which can be defined with @ShellOption annotation.

Actual ValueProvider with annotation based command needs to be registered as a Bean.

Command-line completion currently only support bash and is documented in a built-in completion command Completion.

Support for compiling Spring Shell application into a GraalVM binary mostly comes from Spring Framework and Spring Boot where feature is called AOT. Ahead of Time means that application context is prepared during the compilation time to being ready for GraalVM generation.

Building atop of AOT features from a framework Spring Shell has its own GraalVM configuration providing hints what should exist in a binary. Usually trouble comes from a 3rd party libraries which doesn’t yet contain GraalVM related configurations or those configurations are incomplete.

For gradle add graalvm’s native plugin and configure metadata repository.

When gradle build is run with ./gradlew nativeCompile you should get binary under build/native/nativeCompile directory.

For maven use spring-boot-starter-parent as parent and you’ll get native profile which can be used to do a compilation. You need to configure metadata repository

When maven build is run with ./mvnw package -Pnative you should get binary under target directory.

If everything went well this binary can be run as is instead of executing boot application jar via jvm.

When you use Flow Components to build something that involves use of a multiple components, your implementation may become a bit cluttered. To ease these use cases, we added a ComponentFlow that can hook multiple component executions together as a “flow”.

The following listings show examples of flows and their output in a shell:

Normal execution order of a components is same as defined with a builder. It’s possible to conditionally choose where to jump in a flow by using a next function and returning target component id. If this returned id is aither null or doesn’t exist flow is essentially stopped right there.

Starting from version 2.1.x, a new component model provides an easier way to create higher-level user interaction for the usual use cases, such as asking for input in various forms. These usually are just plain text input or choosing something from a list.

Templates for built-in components are in the org/springframework/shell/component classpath.

Built-in components generally follow this logic:

Current terminal implementations are rich in features and can usually show something else that just plain text. For example a text can be styled to be bold or have different colors. It’s also common for terminals to be able to show various characters from an unicode table like emoji’s which are usually used to make shell output more pretty.

Spring Shell supports these via it’s theming framework which contains two parts, firstly styling can be used to change text type and secondly figures how some characters are shown. These two are then combined together as a theme.

More about theming internals, see Theming.

Modify existing style by overriding settings.

Modify existing figures by overriding settings.

To create a new theme, create a ThemeSettings and provide your own style and figure implementations.

Register a new bean Theme where you can return your custom ThemeSettings and a theme name.

You can use ThemeResolver to resolve styles if you want to create JLine-styled strings programmatically and figures if you want to theme characters for being more pretty.

On default a Spring Boot application will log messages into a console which at minimum is annoying and may also mix output from a shell commands. Fortunately there is a simple way to instruct logging changes via boot properties.

Completely silence console logging by defining its pattern as an empty value.

If you need log from a shell then write those into a file.

If you need different log levels.

Passing contiguration properties as command line options is not supported but you can use any other ways supported by boot, for example.

Version 2.1.x introduced built-in support to distinguish between interactive and non-interactive modes. This makes it easier to use the shell as a simple command-line tool without requiring customization.

Currently, interactive mode is entered if any command line options are passed when starting or running a shell from a command line. This works especially well when a shell application is compiled with Native Support.

Some commands may not have any useful meanings when they run in interactive mode or (conversely) in non-interactive mode. For example, a built-in exit command would have no meaning in non-interactive mode, because it is used to exit interactive mode.

The @ShellMethod annotation has a field called interactionMode that you can use to inform shell about when a particular command is available.

ShellApplicationRunner is a main interface where Boot’s ApplicationArguments are passed and its default implementation makes a choice which ShellRunner is used. There can be only one ShellApplicationRunner but it can be redefined if needed for some reason.

Three ShellRunner implementation exists, named InteractiveShellRunner, NonInteractiveShellRunner and ScriptShellRunner. These are enabled on default but can be disable if needed using properties spring.shell.interactive.enabled, spring.shell.noninteractive.enabled and spring.shell.script.enabled respecively.

Spring Shell provides a number of utilities and annotations to help when testing your application. Test support is provided by two modules: spring-shell-test contains core items, and spring-shell-test-autoconfigure supports auto-configuration for tests.

To test interactive commands.

To test non-interactive commands.

Built in emulation uses terminal width 80 and height 24 on default. Changing dimensions is useful if output would span into multiple lines and you don’t want to handle those cases in a tests.

These can be changed using properties spring.shell.test.terminal-width or spring.shell.test.terminal-height.

ShellTest annotation have fields terminalWidth and terminalHeight which can also be used to change dimensions.

Defining a command registration is a first step to introducing the structure of a command and its options and parameters. This is loosely decoupled from what happens later, such as parsing command-line input and running actual target code. Essentially, it is the definition of a command API that is shown to a user.

Before a command can be executed, we need to parse the command and whatever options the user may have provided. Parsing comes between command registration and command execution.

When command parsing has done its job and command registration has been resolved, command execution does the hard work of running the code.

The CommandContext interface gives access to a currently running context. You can use it to get access to options:

If you need to print something into a shell, you can get a Terminal and use its writer to print something:

The CommandCatalog interface defines how command registrations exist in a shell application. It is possible to dynamically register and de-register commands, which gives flexibility for use cases where possible commands come and go, depending on a shell’s state. Consider the following example:

Styling in a theming is provided by a use of a AttributedString from JLine. Unfortunately styling in JLine is mostly undocumented but we try to go through some of its features here.

In JLine a style spec is a string having a special format. Spec can be given multiple times if separated by a comma. A spec will either define a color for foreground, background or its mode. Special format <spec>:=<spec> allows to define a default within latter spec if former for some reason is invalid.

If spec contains a colon its former part indicates either foreground or background and possible values are foreground, fg, f, background, bg, b, foreground-rgb, fg-rgb, f-rgb, background-rgb, bg-rgb or b-rgb. Without rbg a color value is name from an allowable colors black, red, green, yellow, blue, magenta, cyan or white. Colors have their short formats k, r, g, y, b, m, c and w respectively. If color is prefixed with either ! or bright-, bright mode is automatically applied. Prefixing with ~ will resolve from JLine internal bsd color table.

If rgb format is expected and prefixed with either x or # a normal hex format is used.

If spec contains special names default, bold, faint, italic, underline, blink, inverse, inverse-neg, inverseneg, conceal, crossed-out, crossedout or hidden a style is changed accordingly with an existing color.

If spec is a number or numbers separated with semicolon, format is a plain part of an ansi ascii codes.

SearchMatch is an interface to match text with a pattern. Match results are in a returned value SearchMatchResult. Match result contains info about match positions and overall score of a match.

fzf.