1. Built-In Commands

1.1. Help

Running a shell application often implies that the user is in a graphically limited environment. Also, while we are nearly always connected in the era of mobile phones, accessing a web browser or any other rich UI application (such as a PDF viewer) may not always be possible. This is why it is important that the shell commands are correctly self-documented, and this is where the help command comes in.

Typing help + ENTER lists all the commands known to the shell (including unavailable commands) and a short description of what they do, similar to the following:

my-shell:>help
AVAILABLE COMMANDS

Built-In Commands
       exit: Exit the shell.
       help: Display help about available commands
       stacktrace: Display the full stacktrace of the last error.
       clear: Clear the shell screen.
       quit: Exit the shell.
       history: Display or save the history of previously run commands
       completion bash: Generate bash completion script
       version: Show version info
       script: Read and execute commands from a file.

Typing help <command> shows more detailed information about a command, including the available parameters, their type, whether they are mandatory or not, and other details.

The following listing shows the help command applied to itself:

my-shell:>help help
NAME
       help - Display help about available commands

SYNOPSIS
       help --command String

OPTIONS
       --command or -C String
       The command to obtain help for.
       [Optional]

Help is templated and can be customized if needed. Settings are under spring.shell.command.help where you can use enabled to disable command, grouping-mode taking group or flat if you want to hide groups by flattening a structure, command-template to define your template for output of a command help, commands-template to define output of a command list.

If spring.shell.command.help.grouping-mode=flat is set, then help would show:

my-shell:>help help
AVAILABLE COMMANDS

exit: Exit the shell.
help: Display help about available commands
stacktrace: Display the full stacktrace of the last error.
clear: Clear the shell screen.
quit: Exit the shell.
history: Display or save the history of previously run commands
completion bash: Generate bash completion script
version: Show version info
script: Read and execute commands from a file.

Output from help and help <commmand> are both templated with a default implementation which can be changed.

Option spring.shell.command.help.commands-template defaults to classpath:template/help-commands-default.stg and is passed GroupsInfoModel as a model.

Option spring.shell.command.help.command-template defaults to classpath:template/help-command-default.stg and is passed CommandInfoModel as a model.

Table 1. GroupsInfoModel Variables
Key Description

showGroups

true if showing groups is enabled. Otherwise, false.

groups

The commands variables (see GroupCommandInfoModel Variables).

commands

The commands variables (see CommandInfoModel Variables).

hasUnavailableCommands

true if there is unavailable commands. Otherwise, false.

Table 2. GroupCommandInfoModel Variables
Key Description

group

The name of a group, if set. Otherwise, empty.

commands

The commands, if set. Otherwise, empty. Type is a multi value, see CommandInfoModel Variables.

Table 3. CommandInfoModel Variables
Key Description

name

The name of a command, if set. Otherwise, null. Type is string and contains full command.

names

The names of a command, if set. Otherwise, null. Type is multi value essentially name splitted.

aliases

The possible aliases, if set. Type is multi value with strings.

description

The description of a command, if set. Otherwise, null.

parameters

The parameters variables, if set. Otherwise empty. Type is a multi value, see CommandParameterInfoModel Variables.

availability

The availability variables (see CommandAvailabilityInfoModel Variables).

Table 4. CommandParameterInfoModel Variables
Key Description

type

The type of a parameter if set. Otherwise, null.

arguments

The arguments, if set. Otherwise, null. Type is multi value with strings.

required

true if required. Otherwise, false.

description

The description of a parameter, if set. Otherwise, null.

defaultValue

The default value of a parameter, if set. Otherwise, null.

hasDefaultValue

true if defaultValue exists. Otherwise, false.

Table 5. CommandAvailabilityInfoModel Variables
Key Description

available

true if available. Otherwise, false.

reason

The reason if not available if set. Otherwise, null.

1.2. Clear

The clear command does what you would expect and clears the screen, resetting the prompt in the top left corner.

1.3. Exit

The quit command (also aliased as exit) requests the shell to quit, gracefully closing the Spring application context. If not overridden, a JLine History bean writes a history of all commands to disk, so that they are available again on the next launch.

1.4. Stacktrace

When an exception occurs inside command code, it is caught by the shell and a simple, one-line message is displayed so as not to overflow the user with too much information. There are cases, though, when understanding what exactly happened is important (especially if the exception has a nested cause).

To this end, Spring Shell remembers the last exception that occurred, and the user can later use the stacktrace command to print all the details on the console.

1.5. Script

The script command accepts a local file as an argument and replays commands found there, one at a time.

Reading from the file behaves exactly like inside the interactive shell, so lines starting with // are considered to be comments and are ignored, while lines ending with \ trigger line continuation.

1.6. History

The history command shows the history of commands that has been executed.

There are a few configuration options that you can use to configure behavior of a history. History is kept in a log file, which is enabled by default and can be turned off by setting spring.shell.history.enabled. The name of a log file is resolved from spring.application.name and defaults to spring-shell.log, which you can change by setting spring.shell.history.name.

By default, a log file is generated to a current working directory, which you can dictate by setting spring.shell.config.location. This property can contain a placeholder ({userconfig}), which resolves to a common shared config directory.

Run the Spring Shell application to see how the sample application works as it uses these options.

1.7. Completion

The completion command set lets you create script files that can be used with am OS shell implementations to provide completion. This is very useful when working with non-interactive mode.

Currently, the only implementation is for bash, which works with bash sub-command.

1.8. Version

The version command shows existing build and git info by integrating into Boot’s BuildProperties and GitProperties if those exist in the shell application. By default, only version information is shown, and you can enable other information through configuration options.

The relevant settings are under spring.shell.command.version, where you can use enabled to disable a command and, optionally, define your own template with template. You can use the show-build-artifact, show-build-group, show-build-name, show-build-time, show-build-version, show-git-branch, show-git-commit-id, show-git-short-commit-id and show-git-commit-time commands to control fields in a default template.

The template defaults to classpath:template/version-default.st, and you can define your own, as the following example shows:

<buildVersion>

This setting would output something like the following:

X.X.X

You can add the following attributes to the default template rendering: buildVersion, buildGroup, buildGroup, buildName, buildTime, gitShortCommitId, gitCommitId, gitBranch, and gitCommitTime.