[[cli]] = Spring Boot CLI [partintro] -- The Spring Boot CLI is a command line tool that can be used if you want to quickly develop with Spring. It allows you to 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 can be installed manually; using SDKMAN! (the SDK Manager) or using Homebrew or MacPorts if you are an OSX user. See _<>_ 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] [] Available commands are: run [options] [--] [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] [--] [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: .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: [indent=0,subs="verbatim,quotes,attributes"] ---- $ 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. [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, e.g. [indent=0,subs="verbatim,quotes,attributes"] ---- $ JAVA_OPTS=-Xmx1024m spring run hello.groovy ---- [[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 <>. [[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-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, 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: [source,groovy,indent=0] ---- @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: [source,java,indent=0] ---- @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 https://platform.spring.io/[Spring IO Platform], e.g. `@DependencyManagementBom('io.spring.platform:platform-bom:1.1.2.RELEASE')`. [[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-init]] === Initialize a new project The `init` command allows you to create a new project using https://start.spring.io without leaving the shell. For 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' ---- 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 [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, check the `help` output for more details. For instance, the following command creates a gradle project using 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 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-install-uninstall]] === 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: [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-groovy-beans-dsl]] == Developing application with the Groovy beans DSL Spring Framework 4.0 has native support for a `beans{}` "`DSL`" (borrowed from https://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-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 Please refer to 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-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 _<>_ that you can use with Gradle or Maven.