Spring Boot CLI - Quick Guide

---

---

Spring Boot CLI - Overview

The Spring Boot CLI is a Command Line Interface for Spring Boot. It can be used for a quick start with Spring. It can run Groovy scripts which means that a developer need not write boilerplate code; all that is needed is focus on business logic. Spring Boot CLI is the fastest way to create a Spring-based application.

Features

In this section, we will look at the different features of Spring Boot CL −

• It provides an interface to run and test Spring Boot Application from command prompt.

• It internally use Spring Boot Starter and Spring Boot AutoConfigurate components in order to resolve all dependencies and executes the application.

• It contains Groovy compiler and Grape Dependency Manager.

• It supports Groovy Scripts without external Groovy installation.

• It adds Spring Boot defaults and resolve all dependencies automatically.

Spring Boot CLI - Environment Setup

Spring is a Java-based framework; hence, we need to set up JDK first. Following are the steps needed to setup Spring Boot CLI along with JDK installation.

Step 1 Setup Java Development Kit (JDK)

You can download the latest version of SDK from Oracle's Java site − Java SE Downloads. You will find instructions for installing JDK in downloaded files, follow the given instructions to install and configure the setup. Finally set PATH and JAVA_HOME environment variables to refer to the directory that contains java and javac, typically java_install_dir/bin and java_install_dir respectively.

If you are running Windows and have installed the JDK in C:\jdk-11.0.11, you would have to put the following line in your C:\autoexec.bat file.

set PATH=C:\jdk-11.0.11;%PATH% 
set JAVA_HOME=C:\jdk-11.0.11 

Alternatively, on Windows NT/2000/XP, you will have to right-click on My Computer, select Properties → Advanced → Environment Variables. Then, you will have to update the PATH value and click the OK button.

On Unix (Solaris, Linux, etc.), if the SDK is installed in /usr/local/jdk-11.0.11 and you use the C shell, you will have to put the following into your .cshrc file.

setenv PATH /usr/local/jdk-11.0.11/bin:$PATH 
setenv JAVA_HOME /usr/local/jdk-11.0.11

Step 2 - Install Spring Boot CLI

You can download the latest version of Spring Boot CLI API as ZIP archive from https://repo.spring.io/release/org/springframework/boot/spring-boot-cli/. Once you download the installation, unpack the zip distribution into a convenient location. For example, in E:\Test\spring-boot-cli-2.6.3 on Windows, or /usr/local/spring-boot-cli-2.6.3 on Linux/Unix.

Make sure you set your CLASSPATH variable on this directory properly otherwise you will face a problem while running your application.

Or set the path in command prompt temporarily to run the spring boot application as shown below −

E:/Test/> set path=E:\Test\spring-boot-cli-2.6.3-bin\spring-2.6.3\bin;%PATH%

Step 3 - Verify installation

Run the following command on command prompt to verify the installation −

E:/Test/> spring --version

It should print the following output confirming the successful installation −

Spring CLI v2.6.3

Spring Boot CLI - Hello World Example

In this example, we'll create a Spring Boot + MVC + Rest based Web application.

Step 1: Create source Folder

Create a folder FirstApplication in E:\Test folder.

Step 2: Create Source File

Create FirstApplication.groovy file in E:\Test folder with following source code.

@RestController
class FirstApplication {
   @RequestMapping("/")
   String welcome() {
      "Welcome to TutorialsPoint.Com"
   }
}

Step 3: Run the application

Type the following command

E:/Test/> spring run FirstApplication.groovy

Now Spring Boot CLI will come into action, download required dependencies, run the embedded tomcat, deploy the application and start it. You can see the following output on console.

E:\Test>spring run FirstApplication.groovy
Resolving dependencies...............................

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

2022-02-03 11:12:42.683  INFO 6956 --- [       runner-0] o.s.boot.SpringApplication               : Starting application using Java 11.0.11 on DESKTOP-86KD9FC with PID 6956 (started by intel in F:\Test)
2022-02-03 11:12:42.710  INFO 6956 --- [       runner-0] o.s.boot.SpringApplication               : No active profile set, falling back to default profiles: default
2022-02-03 11:12:45.110  INFO 6956 --- [       runner-0] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2022-02-03 11:12:45.138  INFO 6956 --- [       runner-0] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2022-02-03 11:12:45.139  INFO 6956 --- [       runner-0] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.56]
2022-02-03 11:12:45.229  INFO 6956 --- [       runner-0] org.apache.catalina.loader.WebappLoader  : Unknown class loader [org.springframework.boot.cli.compiler.ExtendedGroovyClassLoader$DefaultScopeParentClassLoader@8646db9] of class [class org.springframework.boot.cli.compiler.ExtendedGroovyClassLoader$DefaultScopeParentClassLoader]
2022-02-03 11:12:45.333  INFO 6956 --- [       runner-0] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2022-02-03 11:12:45.333  INFO 6956 --- [       runner-0] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 2124 ms
2022-02-03 11:12:46.901  INFO 6956 --- [       runner-0] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2022-02-03 11:12:46.930  INFO 6956 --- [       runner-0] o.s.boot.SpringApplication               : Started application in 5.416 seconds (JVM running for 49.049)
2022-02-03 11:13:48.910  INFO 6956 --- [nio-8080-exec-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring DispatcherServlet 'dispatcherServlet'
2022-02-03 11:13:48.912  INFO 6956 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Initializing Servlet 'dispatcherServlet'
2022-02-03 11:13:48.915  INFO 6956 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Completed initialization in 3 ms

Step 4: Browse the application in Browser

Our spring based rest application is now ready. Open url as "https://127.0.0.1:8080/" and you will see the following output.

Welcome to TutorialsPoint.Com

Points to consider

Following actions are taken by Spring CLI.

• All dependency JARs are downloaded for the first time only.

• Spring CLI automatically detects which dependency JARs are to be downloaded based on the classes and annotations used in code.

• Finally it compiles the code, deploy the war on a embedded tomcat, start embedded tomcat server on the default port 8080.

"grab" Dependency Deduction

Standard Groovy codebase contains a @Grab annotation so that dependencies on third-party libraries can be declared. Using @Grab annotation, Grape Dependency Manager downloads jar in similar fashion as that of Maven/Gradle without any build tool. Spring Boot attempts to deduce the required libraries based on code. For example, use of @RestController tells that "Tomcat" and "Spring MVC" libraries are to be grabbed.

Grab Hints

Following table details the hints that Spring Boot uses to download third party libraries −

"grab" Co-ordinates Deduction

We can specify a dependency using @Grab annotation even without specifying group or version. For example,

@Grab('antlr')

Now Spring Boot CLI will download 2.7.7 version of antlr as it is present in Spring Boot's default dependency metadata for 2.6.3 version. Spring Boot maintains all dependency versions by default which are provided in its CLI, Maven dependency management and Gradle plugin. Whenever we declare a dependency of any of those artifacts present in efault dependency metadata without declaring a version, the version listed in its table will be used.

Following table shows all the dependencies and their versions included in the default metadata for Spring Boot CLI 2.6.3 version.

Spring Boot CLI - Default Statements

Default Imports

Spring CLI automatically imports many libraries by default so that explicit imports are not required. Consider the following groovy script.

@RestController
class FirstApplication {
   @RequestMapping("/")
   String welcome() {
      "Welcome to TutorialsPoint.Com"
   }
}

Here import for @RestController, @RequestMapping annotations are already included by default by Spring Boot. We're not even require to use fully-qualified names. You can check by running the application.

Type the following command

E:/Test/> spring run FirstApplication.groovy

You can see the following output on console.

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

2022-02-03 11:29:01.177  INFO 10668 --- [       runner-0] o.s.boot.SpringApplication               : Starting application using Java 11.0.11 on DESKTOP-86KD9FC with PID 10668 (started by intel in F:\Test)
2022-02-03 11:29:01.187  INFO 10668 --- [       runner-0] o.s.boot.SpringApplication               : No active profile set, falling back to default profiles: default
2022-02-03 11:29:03.555  INFO 10668 --- [       runner-0] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2022-02-03 11:29:03.591  INFO 10668 --- [       runner-0] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2022-02-03 11:29:03.592  INFO 10668 --- [       runner-0] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.56]
2022-02-03 11:29:03.659  INFO 10668 --- [       runner-0] org.apache.catalina.loader.WebappLoader  : Unknown class loader [org.springframework.boot.cli.compiler.ExtendedGroovyClassLoader$DefaultScopeParentClassLoader@8646db9] of class [class org.springframework.boot.cli.compiler.ExtendedGroovyClassLoader$DefaultScopeParentClassLoader]
2022-02-03 11:29:03.735  INFO 10668 --- [       runner-0] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2022-02-03 11:29:03.736  INFO 10668 --- [       runner-0] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 2107 ms
2022-02-03 11:29:04.945  INFO 10668 --- [       runner-0] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2022-02-03 11:29:04.968  INFO 10668 --- [       runner-0] o.s.boot.SpringApplication               : Started application in 4.811 seconds (JVM running for 8.805)

Automatic Main Method

We are not required to create standard main method for groovy script to initialize a spring application. It is automatically created for spring boot application.

Spring Boot CLI - Starter Thymeleaf Project

Let's create a sample Thymeleaf based project to demonstrate the capabilities of Spring CLI. Follow the below mentioned step to create a sample project.

TestApplication/message.groovy

@Controller
@Grab('spring-boot-starter-thymeleaf')
class MessageController {
   @RequestMapping("/message")
   String getMessage(Model model) {
      String message = "Welcome to TutorialsPoint.Com!";
      model.addAttribute("message", message);
      return "message";
   }
}

TestApplication/templates/message.html

<!DOCTYPE HTML>
<html xmlns:th="http://www.thymeleaf.org">
   <head> 
      <title>Spring Boot CLI Example</title> 
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   </head>
   <body> 
      <p th:text="'Message: ' + ${message}" />
   </body>
</html> 

TestApplication/static/index.html

<!DOCTYPE HTML>
<html>
   <head> 
      <title>Spring Boot CLI Example</title> 
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   </head>
   <body>
      <p>Go to <a href="/message">Message</a></p>
   </body>
</html> 

Run the application

Type the following command

E:/Test/TestApplication/> spring run *.groovy

Now Spring Boot CLI will come into action, download required dependencies, run the embedded tomcat, deploy the application and start it. You can see the following output on console.

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

2022-02-03 11:36:33.362  INFO 10764 --- [       runner-0] o.s.boot.SpringApplication               : Starting application using Java 11.0.11 on DESKTOP-86KD9FC with PID 10764 (started by intel in E:\Test\TestApplication)
2022-02-03 11:36:33.372  INFO 10764 --- [       runner-0] o.s.boot.SpringApplication               : No active profile set, falling back to default profiles: default
2022-02-03 11:36:35.743  INFO 10764 --- [       runner-0] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2022-02-03 11:36:35.768  INFO 10764 --- [       runner-0] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2022-02-03 11:36:35.769  INFO 10764 --- [       runner-0] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.56]
2022-02-03 11:36:35.829  INFO 10764 --- [       runner-0] org.apache.catalina.loader.WebappLoader  : Unknown class loader [org.springframework.boot.cli.compiler.ExtendedGroovyClassLoader$DefaultScopeParentClassLoader@553a3d88] of class [class org.springframework.boot.cli.compiler.ExtendedGroovyClassLoader$DefaultScopeParentClassLoader]
2022-02-03 11:36:35.896  INFO 10764 --- [       runner-0] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2022-02-03 11:36:35.897  INFO 10764 --- [       runner-0] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 2085 ms
2022-02-03 11:36:36.436  INFO 10764 --- [       runner-0] o.s.b.a.w.s.WelcomePageHandlerMapping    : Adding welcome page: class path resource [static/index.html]
2022-02-03 11:36:37.132  INFO 10764 --- [       runner-0] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2022-02-03 11:36:37.153  INFO 10764 --- [       runner-0] o.s.boot.SpringApplication               : Started application in 4.805 seconds (JVM running for 8.633)
2022-02-03 11:37:03.049  INFO 10764 --- [nio-8080-exec-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring DispatcherServlet 'dispatcherServlet'
2022-02-03 11:37:03.049  INFO 10764 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Initializing Servlet 'dispatcherServlet'
2022-02-03 11:37:03.054  INFO 10764 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Completed initialization in 3 ms

Browse the application in Browser

Our spring based rest application is now ready. Open url as "https://127.0.0.1:8080/" and you will see the following output.

Go to Message

Click on Message link and you will see the following output.

Message: Welcome to TutorialsPoint.Com!

Points to consider

Following actions are taken by Spring CLI.

• @Grab('spring-boot-starter-thymeleaf') annotation directs CLI to download spring-boot-starter-thymeleaf 2.6.3 version.

• Spring CLI automatically detects the version using its metadata as we've not specified any group id or version id here.

• Finally it compiles the code, deploy the war on a embedded tomcat, start embedded tomcat server on the default port 8080.

Spring Boot CLI - Testing Application

In this chapter, we will test the sample project created in Hello World Example Chapter to demonstrate the testing capabilities of Spring CLI. Follow the steps listed in the table below to test the sample project −

FirstApplication/FirstApplication.groovy

@RestController
class FirstApplication {
   @RequestMapping("/")
   
   String welcome() {
      "Welcome to TutorialsPoint.Com"
   }
} 

FirstApplication/TestFirstApplication.groovy

class TestFirstApplication {
   @Test
   void welcomeTest() {
      assertEquals("Welcome to TutorialsPoint.Com", new FirstApplication().welcome())
   }
} 

Run the application

To run the application, type the following command −

E:/Test/FirstApplication/> spring test FirstApplication.groovy TestFirstApplication.groovy

Now Spring Boot CLI will come into action, download the required dependencies, compile the source and test file and unit test the code. The following output will be generated on console −

Resolving dependencies........................................................
.
Time: 0.457

OK (1 test)

Important points

Consider the following points to understand the actions taken by Spring CLI −

• The @Test annotation directs CLI to download JUnit 4.12 version.

• Spring CLI automatically detects the version using its metadata, as we have not specified any dependency.

• Finally, after code compilation, test the application.

Spring Boot CLI - Packaging Application

Spring boot CLI provides jar command in order to package a application as jar file. Let's test the sample project created in Starter Thymeleaf Project Chapter to demonstrate the packaging capabilities of Spring CLI. Follow the below mentioned step to package the sample project.

Package the application

Type the following command

E:/Test/TestApplication/> spring jar TestApplication.jar *.groovy 

Output

Now you can see two new files created in TestApplication folder.

• TestApplication.jar − An executable jar file.

• TestApplication.jar.original − Original jar file.

Include/Exclude

By default following directories are included along with their contents.

• public

• resources

• static

• templates

• META-INF

By default following directories are excluded along with their contents.

• repository

• build

• target

• *.jar files

• *.groovy files

Using --include, we can include directories excluded otherwise. Using --exclude, we can exclude directories included otherwise.

Running the Executable Jar

Type the following command

E:/Test/TestApplication/> java -jar TestApplication.jar

You can see the following output on console.

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

2022-02-03 11:47:42.298  INFO 8908 --- [           main] .b.c.a.PackagedSpringApplicationLauncher : Starting PackagedSpringApplicationLauncher using Java 11.0.11 on DESKTOP-86KD9FC with PID 8908 (E:\Test\TestApplication\TestApplication.jar started by intel in E:\Test\TestApplication)
2022-02-03 11:47:42.310  INFO 8908 --- [           main] .b.c.a.PackagedSpringApplicationLauncher : No active profile set, falling back to default profiles: default
2022-02-03 11:47:44.839  INFO 8908 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2022-02-03 11:47:44.863  INFO 8908 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2022-02-03 11:47:44.864  INFO 8908 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.56]
2022-02-03 11:47:44.958  INFO 8908 --- [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2022-02-03 11:47:44.959  INFO 8908 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1943 ms
2022-02-03 11:47:45.592  INFO 8908 --- [           main] o.s.b.a.w.s.WelcomePageHandlerMapping    : Adding welcome page: class path resource [static/index.html]
2022-02-03 11:47:46.492  INFO 8908 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2022-02-03 11:47:46.514  INFO 8908 --- [           main] .b.c.a.PackagedSpringApplicationLauncher : Started PackagedSpringApplicationLauncher in 5.295 seconds (JVM running for 6.089)

Browse the application in Browser

Our spring based rest application is now ready. Open url as "https://127.0.0.1:8080/" and you will see the following output.

Go to Message

Click on Message link and you will see the following output.

Message: Welcome to TutorialsPoint.Com!

Spring Boot CLI - Creating Project

Spring Boot CLI can be used to create a new project with maven as default build tool using init command. Maven will use https://start.spring.io service. In the following example, we will create a web application using thymeleaf. Go to E:\Test folder and type the following command −

E:/Test> spring init --dependencies = web,thymeleaf MavenApplication.zip

The above command will generate the following output −

Using service at https://start.spring.io
Content saved to MavenApplication.zip

Create Gradle project

We can create a Gradle based project as well by setting --build as gradle. To understand this in a better way, consider the example given below. Go to E:\Test folder and type the following command −

E:/Test> spring init --build = gradle 
--java-version = 1.8 --dependencies = web,thymeleaf 
--packaging = war GradleApplication.zip

The above command will generate the following output −

Using service at https://start.spring.io
Content saved to GradleApplication.zip

Spring Boot CLI - Using Shell

Spring Boot CLI provides a Shell interface to run the commands in which we can directly run the commands as shown below. Go to E:\Test folder and type the following command.

E:/Test> spring shell

You will see the following output.

←[1mSpring Boot←[m←[2m (v2.6.3)←[m
Hit TAB to complete. Type 'help' and hit RETURN for help, and 'exit' to quit.
$

Running commands in Shell.

Type the following and see the output.

version
Spring CLI v2.6.3

You can press tab to auto complete the commands and type exit to finish the shell console.

Testing the application in shell

Type the following and see the output.

$ exit
E:\Test\FirstApplication>