spring-boot/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc

[[cli]]
= Spring Boot CLI

[partintro]
--
The Spring Boot CLI is a command line tool that can be used if you want to quickly
prototype with Spring. It allows you to run Groovy scripts, which means that you have a
familiar Java-like syntax, without so much boilerplate code.
--



[[cli-installation]]
== Installing the CLI
The Spring Boot CLI can be installed manually; using GVM (the Groovy Environment
Manually) or using Homebrew if you are an OSX user. See
'<<getting-started.adoc#getting-started-installing-the-cli>>'
in the ``Getting started'' section for comprehensive installation instructions.



[[cli-using-the-cli]]
== 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:

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ 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:

[indent=0]
----
	$ 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.

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ spring version
	Spring CLI v{spring-boot-version}
----



[[cli-run]]
=== 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:

[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
----
	@RestController
	class WebApplication {

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

	}
----



[[cli-install-uninstall]]
=== Adding dependencies to the CLI
You can add dependencies 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:

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ 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:

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ 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:

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ spring uninstall --all
----



[[cli-deduced-grab-annotations]]
==== 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'':

|===
| Items | Grabs

|`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: See subclasses of
{sc-spring-boot-cli}/compiler/CompilerAutoConfiguration.{sc-ext}[`CompilerAutoConfiguration`]
in the Spring Boot CLI source code to understand exactly how customizations are applied.



[[cli-default-grab-deduced-coordinates]]
==== 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-dependency-versions, appendix>>.



[[cli-default-grab-deduced-coordinates-custom-metadata]]
===== Custom ``grab'' metadata
Spring Boot provides a new annotation, `@GrabMetadata` that can be used to provide custom
dependency metadata that overrides Spring Boot's defaults. This metadata is specified by
using this annotation to provide the coordinates of one or more properties files (deployed
to a Maven repository with a "type" identifier: "properties"). For example
`@GrabMetadata(['com.example:versions-one:1.0.0', 'com.example.versions-two:1.0.0'])` will
pick up files in a Maven repository in "com/example/versions-*/1.0.0/versions-*-1.0.0.properties". The
properties files are applied in the order that they're specified. In the example above, this
means that properties in `versions-two` will override properties in `versions-one`. Each entry
in each properties file must be in the form `group:module=version`. You can use `@GrabMetadata`
anywhere that you can use `@Grab`, however, to ensure consistent ordering of the metadata, you
can only use `@GrabMetadata` at most once in your application. A useful source of dependency
metadata (a superset of Spring Boot) is the http://platform.spring.io/[Spring IO Platform], e.g.
`@GrabMetadata('io.spring.platform:platform-versions:1.0.0.RELEASE')`.



[[cli-default-import-statements]]
==== 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: Many Spring annotations will work without using `import` statements. Try running
your application to see what fails before adding imports.



[[cli-automatic-main-method]]
==== 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`.



[[cli-testing]]
=== Testing your code
The `test` command allows you to compile and run tests for your application. Typical
usage looks like this:

[indent=0]
----
	$ 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):

[source,groovy,indent=0]
----
	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 `test` directory.



[[cli-multiple-source-files]]
=== 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.

[indent=0]
----
	$ spring run *.groovy
----

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

[indent=0]
----
	$ spring test app/*.groovy test/*.groovy
----



[[cli-jar]]
=== Packaging your application
You can use the `jar` command to package your application into a self-contained
executable jar file. For example:

[indent=0]
----
	$ 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

[indent=0]
----
	public/**, resources/**, static/**, templates/**, META-INF/**, *
----

and the default excludes are

[indent=0]
----
	.*, repository/**, build/**, target/**, **/*.jar, **/*.groovy
----

See the output of `spring help jar` for more information.



[[cli-shell]]
=== 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.

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ spring shell
	*Spring Boot* (v{spring-boot-version})
	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:

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ version
	Spring CLI v{spring-boot-version}
----

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.

[[cli-groovy-beans-dsl]]
== Developing application with the Groovy beans DSL
Spring Framework 4.0 has native support for a `beans{}` ``DSL'' (borrowed from
http://grails.org/[Grails]),  and you can embed bean definitions in your Groovy
application scripts using the same format. This is sometimes a good way to include
external features like middleware declarations. For example:

[source,groovy,indent=0]
----
	@Configuration
	class Application implements CommandLineRunner {

		@Autowired
		SharedService service

		@Override
		void run(String... args) {
			println service.message
		}

	}

	import my.company.SharedService

	beans {
		service(SharedService) {
			message = "Hello World"
		}
	}
----

You can mix class declarations with `beans{}` in the same file as long as they stay at
the top level, or you can put the beans DSL in a separate file if you prefer.



[[cli-whats-next]]
== What to read next
There are some {github-code}/spring-boot-cli/samples[sample groovy
scripts] available from the GitHub repository that you can use to try out the
Spring Boot CLI. There is also extensive javadoc throughout the
{sc-spring-boot-cli}[source code].

If you find that you reach the limit of the CLI tool, you will probably want to look
at converting your application to full Gradle or Maven built ``groovy project''. The
next section covers Spring Boot's
'<<build-tool-plugins.adoc#build-tool-plugins, Build tool plugins>>' that you can
use with Gradle or Maven.