Introduction to Spring Shell

Spring Shell is a powerful framework that provides a command-line interface (CLI) to interact with Spring-based applications. It allows developers to create interactive shell applications with ease, enabling users to execute commands, access application functionalities, and manage the application state through a command-line interface. In this article, we'll explore the basics of Spring Shell, including setting up a project, creating commands, and running a simple Spring Shell application.

Setting Up a Spring Shell Project

Create a Spring Boot Project

The first step is to create a new Spring Boot project. If you prefer, you can use Spring Initializr or your preferred IDE.

Add Spring Shell Dependency

In your pom.xml file (for Maven), add the Spring Shell dependency. Java version 17 and above is required for Spring 3.2.

<properties>
	<spring-shell.version>3.2.3</spring-shell.version>
</properties>
<dependencies>
	<dependency>
		<groupId>org.springframework.shell</groupId>
		<artifactId>spring-shell-starter</artifactId>
	</dependency>

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

Create a Simple Command

Create a class for a simple command that will be executed in the Spring Shell application.

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

@ShellComponent
public class HelloWorldCommand {

   @ShellMethod("Say hello")
   public String hello() {
       return "Hello, World!";
   }
}

Explanation

@ShellComponent is used to mark the class as a component that provides shell commands.

@ShellMethod is used to define a method as a shell command. The description provided will be displayed in the shell help.

Run the Spring Shell Application

Now that we have our simple command, we can run the Spring Shell application. Spring Shell provides an interactive shell interface where users can execute commands.

When you run the Spring Shell application, it will start an interactive shell where you can type and execute commands

shell:> hello
Hello, World!

Adding Parameters to Commands

We can also add parameters to our commands. Let's modify the HelloWorldCommand to accept a name parameter:

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

@ShellComponent
public class HelloWorldCommand {

   @ShellMethod("Say hello")
   public String hello(@ShellOption(defaultValue = "World") String name) {
       return "Hello, " + name + "!";
   }
}

Explanation:

@ShellOption is used to define a parameter for the shell command. The defaultValue attribute specifies the default value if the parameter is not provided.

Now, when you run the Spring Shell application and execute the hello command with or without a name parameter, you'll get the respective output.

shell:> hello
Hello, World!

shell:> hello Muthu
Hello, Muthu!

shell:> hello Java
Hello, Java!

Add Simple Calculator Functionality to Shell

Let's add a calculator function to our Spring Shell application. We'll create a new command for adding two integers.

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

@ShellComponent
public class CalculatorCommand {

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

Now, when you run the Spring Shell application, you can execute both the hello command and the add command:

shell:> hello
Hello, World!

shell:> hello Muthu
Hello, Muthu!

shell:> add 5 10
15

Help

Spring Shell has in built support for help. Executing help command displays details about all the commands available as part of the application.

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.

Calculator Command
       add: Add two numbers

Hello World Command
       hello: Say hello

Run and Debug from Spring Tools IDE

As like any other Spring application, it is easy to Run and Debug  from IDE. There are chances you may get below exception

org.springframework.shell.CommandNotFound: No command found for '--spring.output.ansi.enabled=always'
       at org.springframework.shell.Shell.evaluate(Shell.java:207) ~[spring-shell-core-3.2.3.jar:3.2.3]
	at org.springframework.shell.Shell.run(Shell.java:159) ~[spring-shell-core-3.2.3.jar:3.2.3]
	at org.springframework.shell.jline.NonInteractiveShellRunner.run(NonInteractiveShellRunner.java:146) ~[spring-shell-core-3.2.3.jar:3.2.3]

If you get this exception, go to Run Configurations, uncheck the ANSI console output checkbox. This exception will be resolved and commands can be executed in the console.

Source code available in Github

Conclusion

In this article, we've explored the basics of Spring Shell, a framework for creating command-line interfaces for Spring applications. By adding the Spring Shell dependency and creating a simple HelloWorldCommand, we were able to execute commands in an interactive shell. Spring Shell provides annotations like @ShellComponent and @ShellMethod to define components and commands, making it easy to create and manage commands with Spring Boot. Additionally, we learned how to add parameters to commands using @ShellOption, allowing for more dynamic and interactive shell applications. This simple example demonstrates the power and flexibility of Spring Shell in building command-line interfaces for Spring-based applications.