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.5.0.RC1
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
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”:
Items | Grabs |
---|---|
| JDBC Application. |
| JMS Application. |
| Caching abstraction. |
| JUnit. |
| RabbitMQ. |
| Project Reactor. |
extends | Spock test. |
| Spring Batch. |
| Spring Integration. |
| Spring Mobile. |
| Spring MVC + Embedded Tomcat. |
| Spring Security. |
| Spring Transaction Management. |
Tip | |
---|---|
See subclasses of
|
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.
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 | |
---|---|
Many Spring annotations will work without using |
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
.
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')
.
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 | |
---|---|
If you have more than one test source files, you might prefer to organize them
into a |
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
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.
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'
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.5.0.RC1)
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.5.0.RC1
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.
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