1. Getting Started

To see what Spring Shell has to offer, we can write a trivial shell application that has a simple command to add two numbers.

Spring Shell is based on Spring Boot 3.0.0 and Spring Framework 6.0.2 and thus requires JDK 17.

1.1. Writing a Simple Shell Application

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

Spring Shell version on start.spring.io is usually latest release.

With maven you’re expected to have something like:

<properties>
    <spring-shell.version>3.0.0-M3</spring-shell.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-shell-starter</artifactId>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.shell</groupId>
            <artifactId>spring-shell-dependencies</artifactId>
            <version>${spring-shell.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

With gradle you’re expected to have something like:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter'
    implementation 'org.springframework.shell:spring-shell-starter'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.shell:spring-shell-dependencies:3.0.0-M3"
    }
}
Given that Spring Shell starts the REPL (Read-Eval-Print-Loop) because this dependency is present, you need to either skip tests when you build (-DskipTests) throughout this tutorial or remove the sample integration test that was generated by https://start.spring.io. If you do not remove it, the integration test creates the Spring ApplicationContext and, depending on your build tool, stays stuck in the eval loop or crashes with a NPE.

Once compiled it can be run either in interactive mode:

$ $JAVA_HOME/bin/java -jar demo-0.0.1-SNAPSHOT.jar

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::       (v3.0.0)

2022-09-13T18:42:12.818+01:00  INFO 12644 --- [           main] com.example.demo.DemoApplication
: Starting DemoApplication using Java 17.0.4 on ...
2022-09-13T18:42:12.821+01:00  INFO 12644 --- [           main] com.example.demo.DemoApplication
: No active profile set, falling back to 1 default profile: "default"
2022-09-13T18:42:13.606+01:00  INFO 12644 --- [           main] com.example.demo.DemoApplication
: Started DemoApplication in 1.145 seconds (process running for 1.578)
shell:>help
AVAILABLE COMMANDS

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

Or in non-interactive mode:

$JAVA_HOME/bin/java -jar demo-0.0.1-SNAPSHOT.jar help

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::       (v3.0.0)

2022-09-13T18:42:12.818+01:00  INFO 12644 --- [           main] com.example.demo.DemoApplication
: Starting DemoApplication using Java 17.0.4 on ...
2022-09-13T18:42:12.821+01:00  INFO 12644 --- [           main] com.example.demo.DemoApplication
: No active profile set, falling back to 1 default profile: "default"
2022-09-13T18:42:13.606+01:00  INFO 12644 --- [           main] com.example.demo.DemoApplication
: Started DemoApplication in 1.145 seconds (process running for 1.578)
AVAILABLE COMMANDS

Built-In Commands
       help: Display help about available commands
       stacktrace: Display the full stacktrace of the last error.
       clear: Clear the shell screen.
       quit, exit: Exit the shell.
       history: Display or save the history of previously run commands
       version: Show version info
       script: Read and execute commands from a file.
Check out [using-shell-customization-logging] making logging to work better with shell apps.

1.2. Your First Command

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

Then we can create an add method that takes two ints (a and b) and returns their sum. We need to annotate it with @ShellMethod and provide a description of the command in the annotation (the only piece of information that is required):

package com.example.demo;

import org.springframework.shell.standard.ShellMethod;
import org.springframework.shell.standard.ShellComponent;

@ShellComponent
public class MyCommands {

    @ShellMethod("Add two integers together.")
    public int add(int a, int b) {
        return a + b;
    }
}

New add command becomes visible to help:

My Commands
       add: Add two integers together.

And you can run it:

shell:>add --a 1 --b 2
3

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