59. Using the CLI

Once you have installed the CLI you can run it by typing spring. If you run spring without any arguments, a simple help screen is displayed:

$ spring
usage: spring [--help] [--version]
       <command> [<args>]

Available commands are:

  run [options] <files> [--] [args]
    Run a spring groovy script

  ... more command help is shown here

You can use help to get more details about any of the supported commands. For example:

$ spring help run
spring run - Run a spring groovy script

usage: spring run [options] <files> [--] [args]

Option                     Description
------                     -----------
--autoconfigure [Boolean]  Add autoconfigure compiler
                             transformations (default: true)
--classpath, -cp           Additional classpath entries
-e, --edit                 Open the file with the default system
                             editor
--no-guess-dependencies    Do not attempt to guess dependencies
--no-guess-imports         Do not attempt to guess imports
-q, --quiet                Quiet logging
-v, --verbose              Verbose logging of dependency
                             resolution
--watch                    Watch the specified file for changes

The version command provides a quick way to check which version of Spring Boot you are using.

$ spring version
Spring CLI v1.3.5.RELEASE

59.1 Running applications using the CLI

You can compile and run Groovy source code using the run command. The Spring Boot CLI is completely self-contained so you don’t need any external Groovy installation.

Here is an example “hello world” web application written in Groovy:

hello.groovy. 

@RestController
class WebApplication {

    @RequestMapping("/")
    String home() {
        "Hello World!"
    }

}

To compile and run the application type:

$ spring run hello.groovy

To pass command line arguments to the application, you need to use a -- to separate them from the “spring” command arguments, e.g.

$ spring run hello.groovy -- --server.port=9000

To set JVM command line arguments you can use the JAVA_OPTS environment variable, e.g.

$ JAVA_OPTS=-Xmx1024m spring run hello.groovy

59.1.1 Deduced “grab” dependencies

Standard Groovy includes a @Grab annotation which allows you to declare dependencies on a third-party libraries. This useful technique allows Groovy to download jars in the same way as Maven or Gradle would, but without requiring you to use a build tool.

Spring Boot extends this technique further, and will attempt to deduce which libraries to “grab” based on your code. For example, since the WebApplication code above uses @RestController annotations, “Tomcat” and “Spring MVC” will be grabbed.

The following items are used as “grab hints”:

ItemsGrabs

JdbcTemplate, NamedParameterJdbcTemplate, DataSource

JDBC Application.

@EnableJms

JMS Application.

@EnableCaching

Caching abstraction.

@Test

JUnit.

@EnableRabbit

RabbitMQ.

@EnableReactor

Project Reactor.

extends Specification

Spock test.

@EnableBatchProcessing

Spring Batch.

@MessageEndpoint @EnableIntegrationPatterns

Spring Integration.

@EnableDeviceResolver

Spring Mobile.

@Controller @RestController @EnableWebMvc

Spring MVC + Embedded Tomcat.

@EnableWebSecurity

Spring Security.

@EnableTransactionManagement

Spring Transaction Management.

[Tip]Tip

See subclasses of CompilerAutoConfiguration in the Spring Boot CLI source code to understand exactly how customizations are applied.

59.1.2 Deduced “grab” coordinates

Spring Boot extends Groovy’s standard @Grab support by allowing you to specify a dependency without a group or version, for example @Grab('freemarker'). This will consult Spring Boot’s default dependency metadata to deduce the artifact’s group and version. Note that the default metadata is tied to the version of the CLI that you’re using – it will only change when you move to a new version of the CLI, putting you in control of when the versions of your dependencies may change. A table showing the dependencies and their versions that are included in the default metadata can be found in the appendix.

59.1.3 Default import statements

To help reduce the size of your Groovy code, several import statements are automatically included. Notice how the example above refers to @Component, @RestController and @RequestMapping without needing to use fully-qualified names or import statements.

[Tip]Tip

Many Spring annotations will work without using import statements. Try running your application to see what fails before adding imports.

59.1.4 Automatic main method

Unlike the equivalent Java application, you do not need to include a public static void main(String[] args) method with your Groovy scripts. A SpringApplication is automatically created, with your compiled code acting as the source.

59.1.5 Custom dependency management

By default, the CLI uses the dependency management declared in spring-boot-dependencies when resolving @Grab dependencies. Additional dependency management, that will override the default dependency management, can be configured using the @DependencyManagementBom annotation. The annotation’s value should specify the coordinates (groupId:artifactId:version) of one or more Maven BOMs.

For example, the following declaration:

@DependencyManagementBom("com.example.custom-bom:1.0.0")

Will pick up custom-bom-1.0.0.pom in a Maven repository under com/example/custom-versions/1.0.0/.

When multiple BOMs are specified they are applied in the order that they’re declared. For example:

@DependencyManagementBom(["com.example.custom-bom:1.0.0",
        "com.example.another-bom:1.0.0"])

indicates that dependency management in another-bom will override the dependency management in custom-bom.

You can use @DependencyManagementBom anywhere that you can use @Grab, however, to ensure consistent ordering of the dependency management, you can only use @DependencyManagementBom at most once in your application. A useful source of dependency management (that is a superset of Spring Boot’s dependency management) is the Spring IO Platform, e.g. @DependencyManagementBom('io.spring.platform:platform-bom:1.1.2.RELEASE').

59.2 Testing your code

The test command allows you to compile and run tests for your application. Typical usage looks like this:

$ spring test app.groovy tests.groovy
Total: 1, Success: 1, : Failures: 0
Passed? true

In this example, tests.groovy contains JUnit @Test methods or Spock Specification classes. All the common framework annotations and static methods should be available to you without having to import them.

Here is the tests.groovy file that we used above (with a JUnit test):

class ApplicationTests {

    @Test
    void homeSaysHello() {
        assertEquals("Hello World!", new WebApplication().home())
    }

}
[Tip]Tip

If you have more than one test source files, you might prefer to organize them into a test directory.

59.3 Applications with multiple source files

You can use “shell globbing” with all commands that accept file input. This allows you to easily use multiple files from a single directory, e.g.

$ spring run *.groovy

This technique can also be useful if you want to segregate your “test” or “spec” code from the main application code:

$ spring test app/*.groovy test/*.groovy

59.4 Packaging your application

You can use the jar command to package your application into a self-contained executable jar file. For example:

$ spring jar my-app.jar *.groovy

The resulting jar will contain the classes produced by compiling the application and all of the application’s dependencies so that it can then be run using java -jar. The jar file will also contain entries from the application’s classpath. You can add explicit paths to the jar using --include and --exclude (both are comma-separated, and both accept prefixes to the values “+” and “-” to signify that they should be removed from the defaults). The default includes are

public/**, resources/**, static/**, templates/**, META-INF/**, *

and the default excludes are

.*, repository/**, build/**, target/**, **/*.jar, **/*.groovy

See the output of spring help jar for more information.

59.5 Initialize a new project

The init command allows you to create a new project using start.spring.io without leaving the shell. For example:

$ spring init --dependencies=web,data-jpa my-project
Using service at https://start.spring.io
Project extracted to '/Users/developer/example/my-project'

This creates a my-project directory with a Maven-based project using spring-boot-starter-web and spring-boot-starter-data-jpa. You can list the capabilities of the service using the --list flag

$ spring init --list
=======================================
Capabilities of https://start.spring.io
=======================================

Available dependencies:
-----------------------
actuator - Actuator: Production ready features to help you monitor and manage your application
...
web - Web: Support for full-stack web development, including Tomcat and spring-webmvc
websocket - Websocket: Support for WebSocket development
ws - WS: Support for Spring Web Services

Available project types:
------------------------
gradle-build -  Gradle Config [format:build, build:gradle]
gradle-project -  Gradle Project [format:project, build:gradle]
maven-build -  Maven POM [format:build, build:maven]
maven-project -  Maven Project [format:project, build:maven] (default)

...

The init command supports many options, check the help output for more details. For instance, the following command creates a gradle project using Java 8 and war packaging:

$ spring init --build=gradle --java-version=1.8 --dependencies=websocket --packaging=war sample-app.zip
Using service at https://start.spring.io
Content saved to 'sample-app.zip'

59.6 Using the embedded shell

Spring Boot includes command-line completion scripts for BASH and zsh shells. If you don’t use either of these shells (perhaps you are a Windows user) then you can use the shell command to launch an integrated shell.

$ spring shell
Spring Boot (v1.3.5.RELEASE)
Hit TAB to complete. Type \'help' and hit RETURN for help, and \'exit' to quit.

From inside the embedded shell you can run other commands directly:

$ version
Spring CLI v1.3.5.RELEASE

The embedded shell supports ANSI color output as well as tab completion. If you need to run a native command you can use the ! prefix. Hitting ctrl-c will exit the embedded shell.

59.7 Adding extensions to the CLI

You can add extensions to the CLI using the install command. The command takes one or more sets of artifact coordinates in the format group:artifact:version. For example:

$ spring install com.example:spring-boot-cli-extension:1.0.0.RELEASE

In addition to installing the artifacts identified by the coordinates you supply, all of the artifacts' dependencies will also be installed.

To uninstall a dependency use the uninstall command. As with the install command, it takes one or more sets of artifact coordinates in the format group:artifact:version. For example:

$ spring uninstall com.example:spring-boot-cli-extension:1.0.0.RELEASE

It will uninstall the artifacts identified by the coordinates you supply and their dependencies.

To uninstall all additional dependencies you can use the --all option. For example:

$ spring uninstall --all