[[cli]]
= Spring Boot CLI

[partintro]
--
The Spring Boot CLI is a command line tool that you can use if you want to quickly develop
a Spring application. It lets you run Groovy scripts, which means that you have a familiar
Java-like syntax without so much boilerplate code. You can also bootstrap a new project or
write your own command for it.
--



[[cli-installation]]
== Installing the CLI
The Spring Boot CLI (Command-Line Interface) can be installed manually by using SDKMAN!
(the SDK Manager) or by using Homebrew or MacPorts 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` and pressing Enter at
the command line. If you run `spring` without any arguments, a simple help screen is
displayed, as follows:

[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 type `spring help` to get more details about any of the supported commands, as
shown in the following 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, as follows:

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



[[cli-run]]
=== Running Applications with the CLI
You can compile and run Groovy source code by using the `run` command. The Spring Boot CLI
is completely self-contained, so you don't need any external Groovy installation.

The following example shows a "`hello world`" web application written in Groovy:

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

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

	}
----

To compile and run the application type the following command:

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ spring run hello.groovy
----

To pass command-line arguments to the application, use a `--` to separate the commands
from the "`spring`" command arguments, as shown in the following example:

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ spring run hello.groovy -- --server.port=9000
----

To set JVM command line arguments, you can use the `JAVA_OPTS` environment variable, as
shown in the following example:

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ JAVA_OPTS=-Xmx1024m spring run hello.groovy
----

NOTE: When setting `JAVA_OPTS` on Microsoft Windows, make sure to quote the entire
instruction, such as `set "JAVA_OPTS=-Xms256m -Xmx2048m"`. Doing so ensures the values
are properly passed to the process.

[[cli-deduced-grab-annotations]]
==== Deduced "`grab`" Dependencies
Standard Groovy includes a `@Grab` annotation, which lets you declare dependencies on
third-party libraries. This useful technique lets Groovy 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 tries to deduce which libraries to "`grab`"
based on your code. For example, since the `WebApplication` code shown previously uses
`@RestController` annotations, Spring Boot grabs"`Tomcat`" and "`Spring MVC`".

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.

|`@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 letting you specify a dependency
without a group or version (for example, `@Grab('freemarker')`). Doing so consults 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 use – it changes only 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-import-statements]]
==== Default Import Statements
To help reduce the size of your Groovy code, several `import` statements are automatically
included. Notice how the preceding example refers to `@Component`, `@RestController`, and
`@RequestMapping` without needing to use fully-qualified names or `import` statements.

TIP: Many Spring annotations 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-default-grab-deduced-coordinates-custom-dependency-management]]
==== Custom Dependency Management
By default, the CLI uses the dependency management declared in `spring-boot-dependencies`
when resolving `@Grab` dependencies. Additional dependency management, which overrides
the default dependency management, can be configured by using the
`@DependencyManagementBom` annotation. The annotation's value should specify the
coordinates (`groupId:artifactId:version`) of one or more Maven BOMs.

For example, consider the following declaration:

[source,groovy,indent=0]
----
	@DependencyManagementBom("com.example.custom-bom:1.0.0")
----

The preceding declaration picks up `custom-bom-1.0.0.pom` in a Maven repository under
`com/example/custom-versions/1.0.0/`.

When you specify multiple BOMs, they are applied in the order in which you declare them,
as shown in the following example:

[source,java,indent=0]
----
	@DependencyManagementBom(["com.example.custom-bom:1.0.0",
			"com.example.another-bom:1.0.0"])
----

The preceding example indicates that dependency management in `another-bom` overrides 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 use
`@DependencyManagementBom` at most once in your application. A useful source of dependency
management (which is a superset of Spring Boot's dependency management) is the
http://platform.spring.io/[Spring IO Platform], which you might include with the following
line:

[source,java,indent=0]
----
`@DependencyManagementBom('io.spring.platform:platform-bom:1.1.2.RELEASE')`.
----


[[cli-multiple-source-files]]
=== Applications with Multiple Source Files
You can use "`shell globbing`" with all commands that accept file input. Doing so lets
you use multiple files from a single directory, as shown in the following example:

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



[[cli-jar]]
=== Packaging Your Application
You can use the `jar` command to package your application into a self-contained executable
jar file, as shown in the following example:

[indent=0]
----
	$ spring jar my-app.jar *.groovy
----

The resulting jar contains the classes produced by compiling the application and all of
the application's dependencies so that it can then be run by using `java -jar`. The jar
file also contains entries from the application's classpath. You can add explicit paths to
the jar by using `--include` and `--exclude`. Both are comma-separated, and both accept
prefixes, in the form of "`+`" and "`-`", to signify that they should be removed from the
defaults. The default includes are as follows:

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

The default excludes are as follows:

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

Type `spring help jar` on the command line for more information.



[[cli-init]]
=== Initialize a New Project
The `init` command lets you create a new project by using https://start.spring.io without
leaving the shell, as shown in the following example:

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

The preceding example creates a `my-project` directory with a Maven-based project that
uses `spring-boot-starter-web` and `spring-boot-starter-data-jpa`. You can list the
capabilities of the service by using the `--list` flag, as shown in the following example:

[indent=0]
----
	$ 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. See the `help` output for more details. For
instance, the following command creates a Gradle project that uses Java 8 and `war`
packaging:

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



[[cli-shell]]
=== Using the Embedded Shell
Spring Boot includes command-line completion scripts for the BASH and zsh shells. If you
do not use either of these shells (perhaps you are a Windows user), you can use the
`shell` command to launch an integrated shell, as shown in the following example:

[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. To exit the embedded shell, press
`ctrl-c`.



[[cli-install-uninstall]]
=== Adding Extensions to the CLI
You can add extensions to the CLI by using the `install` command. The command takes one
or more sets of artifact coordinates in the format `group:artifact:version`, as shown in
the following 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 are also 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`, as
shown in the following example:

[indent=0,subs="verbatim,quotes,attributes"]
----
	$ spring uninstall com.example:spring-boot-cli-extension:1.0.0.RELEASE
----

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

To uninstall all additional dependencies, you can use the `--all` option, as shown in the
following example:

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



[[cli-groovy-beans-dsl]]
== Developing Applications 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 by using the same format. This is sometimes a good way to include external
features like middleware declarations, as shown in the following 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, if you prefer, you can put the beans DSL in a separate file.



[[cli-maven-settings]]
== Configuring the CLI with `settings.xml`
The Spring Boot CLI uses Aether, Maven's dependency resolution engine, to resolve
dependencies. The CLI makes use of the Maven configuration found in `~/.m2/settings.xml`
to configure Aether. The following configuration settings are honored by the CLI:

 * Offline
 * Mirrors
 * Servers
 * Proxies
 * Profiles
 ** Activation
 ** Repositories
 * Active profiles

See https://maven.apache.org/settings.html[Maven's settings documentation] for further
information.



[[cli-whats-next]]
== What to Read Next
There are some {github-code}/spring-boot-project/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 probably want to look at
converting your application to a full Gradle or Maven built "`Groovy project`". The
next section covers Spring Boot's "<<build-tool-plugins.adoc#build-tool-plugins, Build
tool plugins>>", which you can use with Gradle or Maven.
